mcp-server-codetree
MCP server that gives coding agents structured code understanding via tree-sitter
Ask AI about mcp-server-codetree
Powered by Claude Β· Grounded in docs
I know everything about mcp-server-codetree. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
codetree
An MCP server that gives coding agents structured code understanding via tree-sitter.
Instead of reading entire files, an agent can ask "what classes are in this file?" or "what does this function call?" and get precise, structured answers β saving context window and improving accuracy.
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.
Tools
codetree exposes 16 tools over MCP:
| Tool | Purpose | Example Return |
|---|---|---|
get_file_skeleton(file_path) | Classes, functions, methods with line numbers + doc comments | class Foo β line 5 / def bar(x, y) β line 7 |
get_symbol(file_path, symbol_name) | Full source of a function or class | # calc.py:5\ndef add(a, b): ... |
find_references(symbol_name) | All usages across the repo | calc.py:12 / main.py:34 |
get_call_graph(file_path, function_name) | What a function calls + what calls it | β validate / β main.py:20 |
get_imports(file_path) | Import statements with line numbers | 1: import os / 2: from pathlib import Path |
get_skeletons(file_paths) | Batch skeletons for multiple files | === calc.py ===\nclass Foo β line 1 |
get_symbols(symbols) | Batch source for multiple symbols | # calc.py:1\nclass Foo: ... |
get_complexity(file_path, function_name) | Cyclomatic complexity breakdown | Complexity: 5 (if: 2, for: 1) |
find_dead_code(file_path?) | Symbols defined but never referenced | function unused() β line 15 |
get_blast_radius(file_path, symbol_name) | Transitive impact analysis | Direct callers:\n main.py: run() β line 4 |
detect_clones(file_path?, min_lines?) | Duplicate/near-duplicate functions | Clone group 1 (2 functions, 12 lines) |
get_ast(file_path, symbol_name?, max_depth?) | Raw AST as S-expression | (function_definition [5:0-7:0] ...) |
search_symbols(query?, type?, parent?) | Flexible symbol search with filters | calc.py: class Calculator β line 1 |
rank_symbols(top_n?, file_path?) | Rank symbols by PageRank importance | 1. Foo β line 1 (importance: 12.3%) |
find_tests(file_path, symbol_name) | Find test functions for a symbol | test_calc.py: test_add() β line 3 |
get_variables(file_path, function_name) | Local variables and parameters | Parameters:\n x: int β line 1 |
get_file_skeleton, get_skeletons, and search_symbols accept an optional format="compact" parameter that omits doc comment lines for more concise output.
Supported Languages
| Language | Extensions |
|---|---|
| Python | .py |
| JavaScript | .js, .jsx |
| TypeScript | .ts |
| TSX | .tsx |
| Go | .go |
| Rust | .rs |
| Java | .java |
| C | .c, .h |
| C++ | .cpp, .cc, .cxx, .hpp, .hh |
| Ruby | .rb |
Editor Setup
The --root flag tells codetree which project to analyze. Use . for the current directory, or a full path like /Users/you/my-project.
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.
Architecture
MCP tool call β server.py β indexer.py β LanguagePlugin β tree-sitter β structured result
server.pyβ FastMCP server, defines all 16 toolsindexer.pyβ Discovers files, builds definition index and call graphcache.pyβ.codetree/index.jsonwith mtime-based invalidationregistry.pyβ Maps file extensions to language pluginslanguages/β One plugin per language, each implementing skeleton extraction, symbol lookup, call analysis, and more
Adding a Language
pip install tree-sitter-LANGand add topyproject.toml- Copy
src/codetree/languages/_template.pytolanguages/yourlang.py - Implement the abstract methods
- Register extensions in
registry.py - 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
pytest
# Run a single test file
pytest tests/languages/test_python.py -v
Contributing
Contributions are welcome! Please open an issue to discuss larger changes before submitting a PR.
