Skip to content

README.md

Latest commit

 

History

History
157 lines (124 loc) · 5.49 KB

README.md

File metadata and controls

157 lines (124 loc) · 5.49 KB

Tree-sitter MCP Server & CLI

An MCP server and CLI that uses Tree-sitter to parse and analyze code.

What it does

  • Parse files and get their AST
  • Extract functions and variables
  • Build call graphs
  • Find where functions/variables are used
  • Run custom Tree-sitter queries
  • List imports/includes
  • Extract source code for specific line/column ranges
  • Use as a standalone CLI or as an MCP server for Claude Desktop

Install

Requires Python 3.10+.

# Install directly
uv pip install treesitter-mcp

# Or install a specific version
uv pip install treesitter-mcp==2.1

# Or clone and install
git clone https://github.com/pwno-io/treesitter-mcp.git
cd treesitter-mcp
uv pip install -e .

This installs both treesitter-mcp and ts-cli entry points.

Or run without installing:

uvx treesitter-mcp

Running

As an MCP server (default)

For use with Claude Desktop or other MCP clients:

treesitter-mcp

See docs/MCP_USAGE.md for how to configure.

Standalone CLI (ts-cli)

Run analysis directly from the terminal:

ts-cli path/to/file.py
ts-cli path/to/file.py --ast --max-depth 2
ts-cli path/to/file.py --find-function main --include-source
ts-cli --supported-languages

Use --output-file to write results to JSON files instead of stdout.

HTTP mode

For testing or manual use:

treesitter-mcp --http --port 8000 --host 127.0.0.1

Limiting tools

Only expose certain tools with --tools:

treesitter-mcp --http --port 8000 --tools treesitter_analyze_file,treesitter_get_ast

Or via URL query param: http://127.0.0.1:8000?tools=treesitter_analyze_file,treesitter_get_ast

Tools available:

  • treesitter_analyze_file - Basic analysis
  • treesitter_get_ast - Full AST
  • treesitter_get_call_graph - Function calls
  • treesitter_find_function - Find function definitions
  • treesitter_find_variable - Find variables
  • treesitter_get_source_for_range - Extract source code for a range
  • treesitter_get_supported_languages - What's supported
  • treesitter_get_node_at_point - AST node at a line/column
  • treesitter_get_node_for_range - AST node for a range
  • treesitter_cursor_walk - Walk tree with context
  • treesitter_run_query - Custom Tree-sitter queries
  • treesitter_find_usage - Find symbol usages
  • treesitter_get_dependencies - Extract imports/includes

If you don't specify --tools, everything is exposed.

Writing output to file

All tools support an optional output_file parameter. When provided, the tool writes its result directly to the specified file (as pretty-printed JSON) instead of returning it. This is useful for large outputs like ASTs that could cause context overload in agents.

Example:

# Returns result to file, minimal response to agent
treesitter_get_ast(file_path="large_file.py", output_file="~/output/ast.json")
# Returns: {"status": "written", "output_file": "/home/user/output/ast.json", "bytes_written": 123456}

The tool will:

  • Automatically create parent directories if they don't exist
  • Expand ~ to your home directory
  • Warn (to stderr) if overwriting an existing file
  • Return a minimal confirmation dict on success, or an error dict if writing fails

Including source code in results

The treesitter_find_function and treesitter_find_variable tools support an optional include_source parameter. When set to True, each matched symbol includes its source code in the result:

treesitter_find_function(file_path="server.py", name="main", include_source=True)
# Returns: {"query": "main", "matches": [{"name": "main", ..., "source": "def main():\n    ..."}]}

Language support

Language analyze_file get_ast get_call_graph find_function find_variable find_usage get_dependencies
C ✅ ✅ ✅ ✅ ✅ ✅ ✅
C++ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Python ✅ ✅ ✅ ✅ ✅ ✅ ✅
JavaScript ✅ ✅ ✅ ✅ ✅ ✅ ✅
TypeScript ✅ ✅ ✅ ✅ ✅ ✅ ✅
Go ✅ ✅ ✅ ✅ ✅ ✅ ✅
Java ✅ ✅ ✅ ✅ ✅ ✅ ✅
PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅
Rust ✅ ✅ ✅ ✅ ✅ ✅ ✅
Ruby ✅ ✅ ✅ ✅ ✅ ✅ ✅

File extensions

Language Extensions
C .c
C++ .cpp, .cc, .cxx, .h, .hpp
Python .py
JavaScript .js, .jsx, .mjs, .cjs
TypeScript .ts, .tsx, .cts, .mts
Go .go
Java .java
PHP .php, .phtml
Rust .rs
Ruby .rb

Docs