MCP Tree-sitter Server

A Model Context Protocol (MCP) server that provides code analysis capabilities using tree-sitter, designed to give AI assistants intelligent access to codebases with appropriate context management. Claude Desktop is the reference implementation target.

- 🔍Flexible Exploration: Examine code at multiple levels of granularity
- 🧠Context Management: Provides just enough information without overwhelming the context window
- 🌐Language Agnostic: Supports many programming languages including Python, JavaScript, TypeScript, Go, Rust, C, C++, C#, Swift, Java, Kotlin, Dart, Julia, and APL via tree-sitter-language-pack
- 🌳Structure-Aware: Uses AST-based understanding with efficient cursor-based traversal
- 🔎Searchable: Find specific patterns using text search and tree-sitter queries
- 🔄Caching: Optimized performance through parse tree caching
- 🔑Symbol Extraction: Extract and analyze functions, classes, and other code symbols
- 📊Dependency Analysis: Identify and analyze code dependencies and relationships
- 🧩State Persistence: Maintains project registrations and cached data between invocations
- 🔒Secure: Built-in security boundaries and input validation

For a comprehensive list of all available commands, their current implementation status, and detailed feature matrix, please refer to theFEATURES.mddocument.

git clone https://github.com/wrale/mcp-server-tree-sitter.git cd mcp-server-tree-sitter pip install -e ".[dev]"

You can make the server available in Claude Desktop either through the MCP CLI or by manually configuring Claude Desktop.

Register the server with Claude Desktop:

mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"

Alternatively, you can manually configure Claude Desktop:
-

Open your Claude Desktop configuration file:

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

Create the file if it doesn't exist.

Add the server to themcpServerssection:

{ "mcpServers": { "tree_sitter": { "command": "python", "args": [ "-m", "mcp_server_tree_sitter.server" ] } } }

Alternatively, if using uv or another package manager:

{ "mcpServers": { "tree_sitter": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT", "run", "-m", "mcp_server_tree_sitter.server" ] } } }

Note: Make sure to replace/ABSOLUTE/PATH/TO/YOUR/PROJECTwith the actual absolute path to your project directory.

Save the file and restart Claude Desktop.

The MCP tools icon (hammer) will appear in Claude Desktop's interface once you have properly configured at least one MCP server. You can then access thetree_sitterserver's functionality by clicking on this icon.

If you prefer not to manually install the package from PyPI (released version) or clone the repository, simply use the following configuration for Claude Desktop:
-

Open your Claude Desktop configuration file (same location as above).

Add the tree-sitter server to themcpServerssection:

{ "mcpServers": { "tree_sitter": { "command": "uvx", "args": [ "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT", "mcp-server-tree-sitter" ] } } }

Save the file and restart Claude Desktop.

This method usesuvxto run the installed PyPI package directly, which is the recommended approach for the released version. The server doesn't require any additional parameters to run in its basic configuration.

The MCP Tree-sitter Server maintains state between invocations. This means:

- Projects stay registered until explicitly removed or the server is restarted
- Parse trees are cached according to configuration settings
- Language information is retained throughout the server's lifetime

This persistence is maintained in-memory during the server's lifetime using singleton patterns for key components.

There are several ways to run the server:

python -m mcp run mcp_server_tree_sitter.server

# Show available targets make # Run the server with default settings make mcp-run # Show help information make mcp-run ARGS="--help" # Show version information make mcp-run ARGS="--version" # Run with custom configuration file make mcp-run ARGS="--config /path/to/config.yaml" # Enable debug logging make mcp-run ARGS="--debug" # Disable parse tree caching make mcp-run ARGS="--disable-cache"

# Run the server with default settings mcp-server-tree-sitter # Show help information mcp-server-tree-sitter --help # Show version information mcp-server-tree-sitter --version # Run with custom configuration file mcp-server-tree-sitter --config /path/to/config.yaml # Enable debug logging mcp-server-tree-sitter --debug # Disable parse tree caching mcp-server-tree-sitter --disable-cache

python -m mcp dev mcp_server_tree_sitter.server

register_project_tool(path="/path/to/your/project", name="my-project")

list_files(project="my-project", pattern="/.py")

get_file(project="my-project", path="src/main.py")

get_ast(project="my-project", path="src/main.py", max_depth=3)

get_symbols(project="my-project", path="src/main.py")

find_text(project="my-project", pattern="function", file_pattern="/.py")

run_query( project="my-project", query='(function_definition name: (identifier) @function.name)', language="python" )

analyze_complexity(project="my-project", path="src/main.py")

While the primary intended use is through the MCP server, you can also use the library directly in Python code:

# Import from the API module from mcp_server_tree_sitter.api import ( register_project, list_projects, get_config, get_language_registry ) # Register a project project_info = register_project( path="/path/to/project", name="my-project", description="Description" ) # List projects projects = list_projects() # Get configuration config = get_config() # Access components through dependency injection from mcp_server_tree_sitter.di import get_container container = get_container() project_registry = container.project_registry language_registry = container.language_registry

cache: enabled: true # Enable/disable caching (default: true) max_size_mb: 100 # Maximum cache size in MB (default: 100) ttl_seconds: 300 # Cache entry time-to-live in seconds (default: 300) security: max_file_size_mb: 5 # Maximum file size to process in MB (default: 5) excluded_dirs: # Directories to exclude from processing - .git - node_modules - __pycache__ allowed_extensions: # Optional list of allowed file extensions # - py # - js # Leave empty or omit for all extensions language: default_max_depth: 5 # Default max depth for AST traversal (default: 5) preferred_languages: # List of languages to pre-load at startup for faster performance - python # Pre-loading reduces latency for first operations - javascript log_level: INFO # Logging level (DEBUG, INFO, WARNING, ERROR) max_results_default: 100 # Default maximum results for search operations

configure(config_path="/path/to/config.yaml")

The server's logging verbosity can be controlled using environment variables:

# Enable detailed debug logging export MCP_TS_LOG_LEVEL=DEBUG # Use normal informational logging (default) export MCP_TS_LOG_LEVEL=INFO # Only show warning and error messages export MCP_TS_LOG_LEVEL=WARNING

For comprehensive information about logging configuration, please refer to thelogging documentation. For details on the command-line interface, see theCLI documentation.

configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")

export MCP_TS_CACHE_MAX_SIZE_MB=256 export MCP_TS_LOG_LEVEL=DEBUG export MCP_TS_CONFIG_PATH=/path/to/config.yaml

# Run diagnostic tests make test-diagnostics # CI-friendly version (won't fail the build on diagnostic issues) make test-diagnostics-ci

Diagnostic tests provide detailed information about the server's behavior and can help isolate specific issues. For more information about the diagnostic framework, please see thediagnostics documentation.

The MCP Tree-sitter Server maintains type safety when interfacing with tree-sitter libraries through careful design patterns and protocols. If you're extending the codebase, please review thetype safety guidefor important information about handling tree-sitter API variations.

SeeFEATURES.mdfor detailed information about each tool's implementation status, dependencies, and usage examples.

- Questions & Feature Requests:GitHub Discussions
- Bug Reports:GitHub Issues

Visual Studio extension with 20 Roslyn-powered MCP tools for AI assistants. Semantic code navigation, symbol search, inheritance, call graphs, safe rename, build/test.