Tree-sitter MCP Server

How to use

You will run the server locally and connect an MCP client to it. Start the server in stdio mode (local process) and register it with your MCP client or toolchain. Use the provided commands to either run from source or use the released package, and then interact with a registered project to list files, inspect the AST, extract symbols, run queries, and analyze dependencies and complexity.

How to install

# Prerequisites
# - Python 3.10+
# - Tree-sitter language parsers for your preferred languages

# Basic installation from PyPI
pip install mcp-server-tree-sitter

# Development installation (clone and install with dev features)
git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev,languages]"

State persistence and running notes

The server maintains state across invocations. Projects stay registered until you remove them or restart the server, and parsed trees can be cached based on your configuration.

You can run the server as a standalone process using one of the following approaches.

Running as a standalone server

# Run via the Python module
python -m mcp run mcp_server_tree_sitter.server

# Show available Makefile targets
make

# Run with default settings
make mcp-run

# Show help
make mcp-run ARGS="--help"

# Show version
make mcp-run ARGS="--version"

# Run with a custom config 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"
```

```bash
# Or run the installed script directly
mcp-server-tree-sitter

# Help and version
mcp-server-tree-sitter --help
mcp-server-tree-sitter --version

# Custom config
mcp-server-tree-sitter --config /path/to/config.yaml

# Debug and disable cache
mcp-server-tree-sitter --debug
mcp-server-tree-sitter --disable-cache

Using with the MCP Inspector

# Interact with the MCP CLI to dev-inspect without a full GUI
python -m mcp dev mcp_server_tree_sitter.server
```

```bash
make mcp-dev
```

```bash
make mcp-dev ARGS="--debug"

Configuration and runtime behavior

Configure how the server caches data, security limits, and default AST traversal depth via a YAML config. The server reads configuration by precedence: environment variables, configure() calls, YAML file, then defaults.

Examples of configuration you can provide include cache settings, security limits, language preferences, and logging levels.

Usage: common tasks with a registered project

Register a project to enable analysis and exploration:

- register a project with a name and path

Then you can explore files, view ASTs, extract symbols, and run queries.

Direct Python usage

# 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

Example configuration snippets

cache:
  enabled: true
  max_size_mb: 100
  ttl_seconds: 300

security:
  max_file_size_mb: 5
  excluded_dirs:
    - .git
    - node_modules
    - __pycache__
  allowed_extensions:
    # - py
    # - js

language:
  default_max_depth: 5
  preferred_languages:
    - python
    - javascript

log_level: INFO
max_results_default: 100

Logging and environment configuration

Control logging with environment variables when running the server. For example, set the log level to DEBUG to diagnose issues.

Environment variable examples that affect configuration include MCP_TS_LOG_LEVEL and MCP_TS_CONFIG_PATH.

Tools and endpoints you can use

You will interact with a variety of tools to manage projects, query code, and analyze structure. The server exposes capabilities such as listing files, fetching file content and ASTs, running tree-sitter queries, symbol extraction, and dependency analysis.

Notes and best practices

If you need fast startup for common languages, preload selected parsers in the configuration. Pre-loading helps reduce latency for first analyses on those languages.

register_project_tool

Registers a new project for analysis by the MCP Tree-sitter Server.

list_projects_tool

Lists all registered projects.

remove_project_tool

Removes a registered project from the server.

list_languages

Lists languages supported by the tree-sitter parsers.

check_language_available

Checks if a language parser is available for a given language.

list_files

Lists files in a registered project, with optional pattern matching.

get_file

Retrieves the content of a specified file in a project.

get_file_metadata

Fetches metadata for a file in a project.

get_ast

Gets the AST for a file up to a specified depth.

get_node_at_position

Finds the AST node at a given position.

find_text

Searches for text patterns within a project.

run_query

Executes a tree-sitter query against the project code.

get_symbols

Extracts defined symbols such as functions and classes.

find_usage

Finds usages of a symbol within the codebase.

analyze_project

Performs a high-level analysis of a project.

get_dependencies

Identifies and analyzes code dependencies.

analyze_complexity

Analyzes code complexity for a given path.

get_query_template_tool

Provides templates for building queries.

list_query_templates_tool

Lists available query templates.

build_query

Builds a query from a template and parameters.

adapt_query

Adapts a query to a specific language context.

get_node_types

Gets the types of AST nodes available for queries.

find_similar_code

Detects code that is similar to a given snippet.

clear_cache

Clears the internal parse/cached data.

diagnose_config

Runs diagnostics on the current server configuration.