🦘 Clangaroo: Fast C++ code intelligence for LLMs via MCP

✨ About

Clangaroo enables Claude Code, Gemini CLI, and other coding agents to jump around your C++ codebase with ease. Clangaroo provides fast, direct lookup of C/C++ symbols, functions, definitions, call hierarchies, type hierarchies, and more by your bestest LLM pals.

Clangaroo combines the speed of Tree-sitter parsing with the accuracy of clangd LSP, optionally enhanced by Google Gemini Flash AI for deeper insights. Let your AI buddies spend more time coding and less time stumbling around.

But WHY did you make this? I ❤️ using Claude Code, but every time it auto-compacts and then starts grepping around for the function we've been working on for forever, I die a little bit inside. But aren't there already a few MCPs that do this - why do we need another? I spent some time searching and found both MCP-language-server and Serena, which both look perfectly nice! Unfortunately, neither worked for me 😭

Clangaroo is meant to be super simple and is intended to 'just work'.

📚 Table of Contents

• 🚀 Quick Start
• 🎯 Features
• 💬 Usage Examples
• 🛠️ Available Tools
• 🤖 AI Features (Optional)
• ⚙️ Configuration Reference
• 📋 Requirements
• 🔧 Troubleshooting
• 📄 License
• 🙏 Acknowledgments

🚀 Quick Start

1. Install Clangaroo

git clone https://github.com/jasondk/clangaroo
cd clangaroo
pip install -e .

2. Special compilation step for your C++ project

The clang LSP needs you to do this once:

# For Makefile-based projects
make clean
compiledb make

# (Some people prefer using 🐻)
bear -- make

# For CMake projects
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cp build/compile_commands.json .

This will create a special compile_commands.json file in your project root.

3. Configure Claude Desktop or other MCP client

Did you know you can now add MCP servers to LM Studio?

🎯 Recommended configuration with AI:

N.B.: Use of --ai-enabled will use Google Gemini and will incur a small cost via your Gemini API key, if provided. This is usually very minor as long as you use Gemini Flash or Flash Lite.

Note: Please replace 'command' and 'project' with correct paths for your system, and replace your-google-ai-api-key with your API key (if using one). If you don't wish to use the AI enhanced services, simply leave out all the --ai options and the API key.

{
  "mcpServers": {
    "clangaroo": {
      "command": "/usr/local/bin/clangaroo",
      "args": [
        "--project", "/path/to/your/cpp/project",
        "--warmup",
        "--warmup-limit", "10",
        "--log-level", "info",
        "--ai-enabled",
        "--ai-provider", "gemini-2.5-flash",
        "--ai-cache-days", "14",
        "--ai-cost-limit", "15.0",
        "--call-hierarchy-depth", "10",
        "--ai-analysis-level", "summary",
        "--ai-context-level", "minimal"
      ],
      "env": {
        "CLANGAROO_AI_API_KEY": "your-google-ai-api-key"
      }
    }
  }
}

📍 Claude Desktop config file locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Default depth of AI analysis (--ai-analysis-level, default: summary).

• summary: Quick overview with key points
  
• detailed: Comprehensive analysis with examples and context
  

Default depth of context (`--ai-context-level`, default: `minimal`).
- `minimal`: Just the symbol and immediate documentation
- `local`: Include surrounding code in the same file
- `full`: Include dependencies and related files

4. Restart Claude Desktop

Quit and restart Claude. You're ready to explore your C++ code! 🎉

5. Add MCP server to Claude Code

claude mcp add-from-claude-desktop (and make sure clangaroo is checked)

OR

claude mcp add /usr/local/bin/clangaroo --project /path/to/your/cpp/project --warmup --warmup-limit 10 --log-level info --ai-enabled --ai-provider gemini-2.5-flash --ai-cache-days 14 --ai-cost-limit 15.0 --call-hierarchy-depth 10 --ai-analysis-level summary --ai-context-level minimal --name clangaroo --env CLANGAROO_AI_API_KEY=your-google-ai-api-key

🎯 Features

• ⚡ Ultra-Fast Navigation: Fast response times for code structure queries
• 🔍 Smart Symbol Search: Hybrid Tree-sitter + clangd search with automatic fallback
• 📊 Deep Code Analysis: Call hierarchies, type hierarchies, and reference tracking
• 🤖 AI-Powered Insights: Documentation summarization, pattern detection, and architectural analysis
• 💪 Robust: Works even with compilation errors thanks to Tree-sitter fallback
• 🚀 Zero Configuration: Just point to a project with compile_commands.json

💬 Usage Examples

This is really meant for coding agents like Claude Code more than you, but if you want to use it, you can just talk to your LLM naturally about your code once the MCP server is hooked up:

"Uncover the cryptic lair where the `UserManager` class is conjured from the void."  
"Reveal every shadowy corner that invokes the dreaded `summonSoulPayment()` ritual."  
"Expose the unholy powers inherited by the `DatabaseConnection` class from its ancient ancestors."  
"Dissect the twisted call hierarchy of `unleashChaos()` and narrate the program's descent into madness."
#YMMV

🛠️ Available Tools

Tool Category	Tools	Description
🔍 Discovery	cpp_list_files cpp_search_symbols	Find files and symbols in your codebase
📍 Navigation	cpp_definition cpp_references cpp_hover	Jump to definitions, find references, get type info
📞 Call Analysis	cpp_incoming_calls cpp_outgoing_calls	Trace function relationships
🏗️ Type Hierarchy	cpp_prepare_type_hierarchy cpp_supertypes cpp_subtypes	Analyze inheritance
⚡ Structure	cpp_list_functions cpp_list_classes cpp_get_outline cpp_extract_signatures	Fast structural analysis

🤖 AI Features (Optional)

Setup

1. Get your API key from Google AI Studio
2. Add to your environment (bash):

   export CLANGAROO_AI_API_KEY="your-api-key"
   

What You Get

• 📚 Smart Documentation: Complex C++ docs explained clearly
• 🔍 Pattern Analysis: Understand why and how functions are called
• 🏛️ Architecture Insights: Identify design patterns automatically
• 💡 Refactoring Tips: Get improvement recommendations
• 💰 Cost Effective: $3-7/month typical usage with smart caching

⚙️ Configuration Reference

View all configuration options

Basic Options

• --project PATH - Path to C++ project root (required)
• --log-level LEVEL - Logging verbosity: debug, info, warning, error
• --timeout SECONDS - LSP request timeout (default: 5.0)

Performance Options

• --warmup - Pre-warm the index by opening key files
• --warmup-limit N - Number of files to warm up (default: 10)
• --wait-for-index - Wait for clangd indexing to complete
• --index-timeout SECONDS - Timeout for index wait (default: 300)
• --index-path PATH - Custom clangd index location

AI Options

• --ai-enabled - Enable AI features
• --ai-provider PROVIDER - AI provider: gemini-2.5-flash or gemini-2.5-flash-lite
• --ai-api-key KEY - Google AI API key
• --ai-cache-days DAYS - Cache AI summaries for N days (default: 7)
• --ai-cost-limit AMOUNT - Monthly cost limit in USD (default: 10.0)
• --ai-analysis-level LEVEL - Default analysis depth: summary or detailed
• --ai-context-level LEVEL - Code context depth: minimal, local, or full

Call Hierarchy Options

• --call-hierarchy-depth DEPTH - Maximum depth (1-10, default: 3)
• --call-hierarchy-max-calls NUM - Total call limit (default: 100)
• --call-hierarchy-per-level NUM - Calls per depth level (default: 25)

📋 Requirements

• Python 3.10+
• clangd 16+ (brew install llvm or apt install clangd)
• C++ project with compile_commands.json
• (Optional) Google AI API key for AI features

🔧 Troubleshooting

Claude doesn't see the tools

1. Check the config file location and JSON syntax
2. Use absolute paths in the configuration
3. Restart Claude Desktop completely
4. Check logs with --log-level debug

No results from queries

1. Verify compile_commands.json includes the files
2. Wait for indexing: add --wait-for-index flag
3. Test clangd directly: clangd --check=file.cpp

Performance issues

• Enable warmup: --warmup --warmup-limit 30
• Use shared index: --index-path /shared/clangd-index
• Reduce call hierarchy depth for large codebases

📄 License

MIT License - see the file for details.

🙏 Acknowledgments

• clangd for C++ language server
• Tree-sitter for syntax parsing
• MCP for the protocol specification
• Google Gemini for AI capabilities

---