Clangaroo

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

✨ About

NOTE (January 2026): Claude Code now has built-in support for LSPs, making this unnecessary. Since it may still be useful in other agentic harnesses I'll leave the project here for now.

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

🎯 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

🛠️ Available Tools

🤖 AI Features (Optional)

Setup

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

   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

📄 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

🚀 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?

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"
      }
    }
  }
}

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

💬 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

⚙️ Configuration Reference

📋 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