Integrations
Integrates with Git repositories by recognizing and excluding .git directories from analysis
Provides language-specific code parsing and analysis for JavaScript files, with symbol extraction and AST-based understanding
Enables analysis of Julia code with tree-sitter parsing, symbol extraction, and dependency analysis
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.
Features
- 🔍 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++, Swift, Java, Kotlin, 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 the FEATURES.md document.
Installation
Prerequisites
- Python 3.10+
- Tree-sitter language parsers for your preferred languages
Basic Installation
Development Installation
Quick Start
Running with Claude Desktop
You can make the server available in Claude Desktop either through the MCP CLI or by manually configuring Claude Desktop.
Using MCP CLI
Register the server with Claude Desktop:
Manual Configuration
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.
- macOS/Linux:
- Add the server to the
mcpServers
section:Alternatively, if using uv or another package manager:CopyNote: Make sure to replaceCopy/ABSOLUTE/PATH/TO/YOUR/PROJECT
with 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 the tree_sitter
server's functionality by clicking on this icon.
Configuring with Released Version
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 the
mcpServers
section:Copy - Save the file and restart Claude Desktop.
This method uses uvx
to 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.
State Persistence
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.
Running as a standalone server
There are several ways to run the server:
Using the MCP CLI directly:
Using Makefile targets:
Using the installed script:
Using with the MCP Inspector
Using the MCP CLI directly:
Or using the Makefile target:
You can also pass arguments:
Usage
Register a Project
First, register a project to analyze:
Explore Files
List files in the project:
View file content:
Analyze Code Structure
Get the syntax tree:
Extract symbols:
Search Code
Search for text:
Run tree-sitter queries:
Analyze Complexity
Direct Python Usage
While the primary intended use is through the MCP server, you can also use the library directly in Python code:
Configuration
Create a YAML configuration file:
Load it with:
Logging Configuration
The server's logging verbosity can be controlled using environment variables:
For comprehensive information about logging configuration, please refer to the logging documentation. For details on the command-line interface, see the CLI documentation.
About preferred_languages
The preferred_languages
setting controls which language parsers are pre-loaded at server startup rather than on-demand. This provides several benefits:
- Faster initial analysis: No delay when first analyzing a file of a pre-loaded language
- Early error detection: Issues with parsers are discovered at startup, not during use
- Predictable memory allocation: Memory for frequently used parsers is allocated upfront
By default, all parsers are loaded on-demand when first needed. For optimal performance, specify the languages you use most frequently in your projects.
You can also configure specific settings:
Or use environment variables:
Environment variables use the format MCP_TS_SECTION_SETTING
(e.g., MCP_TS_CACHE_MAX_SIZE_MB
) for section settings, or MCP_TS_SETTING
(e.g., MCP_TS_LOG_LEVEL
) for top-level settings.
Configuration values are applied in this order of precedence:
- Environment variables (highest)
- Values set via
configure()
calls - YAML configuration file
- Default values (lowest)
The server will look for configuration in:
- Path specified in
configure()
call - Path specified by
MCP_TS_CONFIG_PATH
environment variable - Default location:
~/.config/tree-sitter/config.yaml
For Developers
Diagnostic Capabilities
The MCP Tree-sitter Server includes a diagnostic framework to help identify and fix issues:
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 the diagnostics documentation.
Type Safety Considerations
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 the type safety guide for important information about handling tree-sitter API variations.
Available Resources
The server provides the following MCP resources:
project://{project}/files
- List all files in a projectproject://{project}/files/{pattern}
- List files matching a patternproject://{project}/file/{path}
- Get file contentproject://{project}/file/{path}/lines/{start}-{end}
- Get specific lines from a fileproject://{project}/ast/{path}
- Get the AST for a fileproject://{project}/ast/{path}/depth/{depth}
- Get the AST with custom depth
Available Tools
The server provides tools for:
- Project management:
register_project_tool
,list_projects_tool
,remove_project_tool
- Language management:
list_languages
,check_language_available
- File operations:
list_files
,get_file
,get_file_metadata
- AST analysis:
get_ast
,get_node_at_position
- Code search:
find_text
,run_query
- Symbol extraction:
get_symbols
,find_usage
- Project analysis:
analyze_project
,get_dependencies
,analyze_complexity
- Query building:
get_query_template_tool
,list_query_templates_tool
,build_query
,adapt_query
,get_node_types
- Similar code detection:
find_similar_code
- Cache management:
clear_cache
- Configuration diagnostics:
diagnose_config
See FEATURES.md for detailed information about each tool's implementation status, dependencies, and usage examples.
Available Prompts
The server provides the following MCP prompts:
code_review
- Create a prompt for reviewing codeexplain_code
- Create a prompt for explaining codeexplain_tree_sitter_query
- Explain tree-sitter query syntaxsuggest_improvements
- Create a prompt for suggesting code improvementsproject_overview
- Create a prompt for a project overview analysis
License
MIT
You must be authenticated.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol (MCP) server that provides code analysis capabilities using tree-sitter, designed to give Claude intelligent access to codebases with appropriate context management.
- Features
- Installation
- Quick Start
- State Persistence
- Usage
- Direct Python Usage
- Configuration
- For Developers
- Available Resources
- Available Tools
- Available Prompts
- License
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityAn implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.Last updated -886JavaScriptMIT License
- -security-license-qualityA specialized server that helps users create new Model Context Protocol (MCP) servers by providing tools and templates for scaffolding projects with various capabilities.Last updated -1TypeScript
- -securityAlicense-qualityAn implementation of the Model Context Protocol (MCP) that enables interaction with debug adapters, allowing language models to control debuggers, set breakpoints, evaluate expressions, and navigate source code during debugging sessions.Last updated -2PythonAGPL 3.0
- -securityAlicense-qualityA Model Context Protocol server that enables IDEs like Cursor and Windsurf to analyze large codebases using Gemini's extensive context window.Last updated -17PythonMIT License