Basic Installation

pip install mcp-server-tree-sitter

Development Installation

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

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:

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

Manual Configuration

Alternatively, you can manually configure Claude Desktop:

1. 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.

2. Add the server to the mcpServers section:

   {
       "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/PROJECT with the actual absolute path to your project directory.

3. 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:

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

2. Add the tree-sitter server to the mcpServers section:

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

3. 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:

python -m mcp run mcp_server_tree_sitter.server

Using Makefile targets:

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

Using the installed script:

# 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

Using with the MCP Inspector

Using the MCP CLI directly:

python -m mcp dev mcp_server_tree_sitter.server

Or using the Makefile target:

make mcp-dev

You can also pass arguments:

make mcp-dev ARGS="--debug"

Usage

Register a Project

First, register a project to analyze:

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

Explore Files

List files in the project:

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

View file content:

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

Analyze Code Structure

Get the syntax tree:

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

Extract symbols:

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

Search Code

Search for text:

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

Run tree-sitter queries:

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

Analyze Complexity

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

Direct Python Usage

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

Configuration

Create a YAML configuration file:

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

Load it with:

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

Logging Configuration

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