codetree

Stop feeding entire files to your AI agent.

codetree is an MCP server that gives coding agents structured code understanding via tree-sitter — so they ask precise questions instead of reading thousands of lines. 23 tools, 10 languages, ~1 second startup. No vector DB, no embedding model, no config.

Quick Start

Prerequisite: Install uv if you don't have it (curl -LsSf https://astral.sh/uv/install.sh | sh).

Then cd into any project and run:

claude mcp add codetree -- uvx --from mcp-server-codetree codetree --root .

That's it. The . means "this project." Your agent now has structured code understanding.

Not using Claude Code? See Editor Setup for Cursor, VS Code, Windsurf, and Claude Desktop.

Before / After

Before codetree — agent reads the raw file:

$ cat calculator.py
import math
from typing import Optional

class Calculator:
    """A scientific calculator with memory."""

    def __init__(self):
        self.memory = 0
        self.history = []

    def add(self, a: float, b: float) -> float:
        """Add two numbers."""
        result = a + b
        self.history.append(('add', a, b, result))
        return result

    def divide(self, a: float, b: float) -> Optional[float]:
        """Divide a by b, returns None on zero division."""
        if b == 0:
            return None
        result = a / b
        self.history.append(('divide', a, b, result))
        return result

    # ... 200 more lines of methods ...

Tokens consumed: ~2,000+ for the full file

After codetree — agent asks for the skeleton:

class Calculator → line 4
  "A scientific calculator with memory."
  def __init__(self) (in Calculator) → line 7
  def add(self, a: float, b: float) (in Calculator) → line 11
    "Add two numbers."
  def divide(self, a: float, b: float) (in Calculator) → line 17
    "Divide a by b, returns None on zero division."
  def sqrt(self, x: float) (in Calculator) → line 24
    "Square root using math.sqrt."

Tokens consumed: ~80. That's a 25x reduction.

The agent sees every class, method, and docstring — with line numbers — without reading a single function body. When it needs the full source of divide, it calls get_symbol("calculator.py", "divide") and gets just those 6 lines.

23 Tools

Understand Structure

Navigate Relationships

Analyze Quality

Inspect & Search

Onboarding & Graph

Change & Dataflow

Visualization & History

get_file_skeleton, get_skeletons, and search_symbols accept format="compact" for even fewer tokens.

Supported Languages

Editor Setup

The --root flag tells codetree which project to analyze. Use . for the current directory, or a full path.

Claude Code

cd into your project, then:

claude mcp add codetree -- uvx --from mcp-server-codetree codetree --root .

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "codetree": {
      "command": "uvx",
      "args": ["--from", "mcp-server-codetree", "codetree", "--root", "${workspaceFolder}"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "codetree": {
      "command": "uvx",
      "args": ["--from", "mcp-server-codetree", "codetree", "--root", "${workspaceFolder}"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codetree": {
      "command": "uvx",
      "args": ["--from", "mcp-server-codetree", "codetree", "--root", "${workspaceFolder}"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "codetree": {
      "command": "uvx",
      "args": ["--from", "mcp-server-codetree", "codetree", "--root", "/path/to/your/project"]
    }
  }
}

Claude Desktop doesn't support ${workspaceFolder}, so use a full path here.

Why codetree?

Architecture

Agent (Claude, Copilot, Cursor, etc.)
    │ MCP (stdio)
    ▼
codetree server (FastMCP)
    │
    ├── Indexer → LanguagePlugin → tree-sitter → structured results
    │   Cache (.codetree/index.json, mtime-based)
    │
    └── Graph Layer → SQLite (.codetree/graph.db)
        Persistent symbols + edges, incremental updates
        Change impact, dataflow, taint analysis

Adding a Language

1. pip install tree-sitter-LANG and add to pyproject.toml
2. Copy src/codetree/languages/_template.py to languages/yourlang.py
3. Implement the abstract methods
4. Register extensions in registry.py
5. Add tests

Development

git clone https://github.com/ThinkyMiner/codeTree.git
cd codeTree
python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install pytest

# Run all tests (~1058 tests, ~35s)
pytest

# Run a single test file
pytest tests/languages/test_python.py -v

Contributing

Contributions welcome! See CONTRIBUTING.md for setup instructions and guidelines.