Skip to content
Back to search

mcp-server-tree-sitter

MCP Server for Tree-sitter

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wrale--mcp-server-tree-sitter/badge.svg)](/listings/wrale--mcp-server-tree-sitter)

HTML

<a href="/listings/wrale--mcp-server-tree-sitter"><img src="/api/listings/wrale--mcp-server-tree-sitter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 469 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Tree-sitter Server
  2. 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.
  3. ## Features
  4. - 🔍 **Flexible Exploration**: Examine code at multiple levels of granularity
  5. - 🧠 **Context Management**: Provides just enough information without overwhelming the context window
  6. - 🌐 **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
  7. - 🌳 **Structure-Aware**: Uses AST-based understanding with efficient cursor-based traversal
  8. - 🔎 **Searchable**: Find specific patterns using text search and tree-sitter queries
  9. - 🔄 **Caching**: Optimized performance through parse tree caching
  10. - 🔑 **Symbol Extraction**: Extract and analyze functions, classes, and other code symbols
  11. - 📊 **Dependency Analysis**: Identify and analyze code dependencies and relationships
  12. - 🧩 **State Persistence**: Maintains project registrations and cached data between invocations
  13. - 🔒 **Secure**: Built-in security boundaries and input validation
  14. For a comprehensive list of all available commands, their current implementation status, and detailed feature matrix, please refer to the [FEATURES.md](FEATURES.md) document.
  15. ## Installation
  16. ### Prerequisites
  17. - Python 3.10+
  18. - Tree-sitter language parsers for your preferred languages
  19. ### Basic Installation
  20. ```bash
  21. pip install mcp-server-tree-sitter
  22. ```
  23. ### Development Installation
  24. ```bash
  25. git clone https://github.com/wrale/mcp-server-tree-sitter.git
  26. cd mcp-server-tree-sitter
  27. pip install -e ".[dev]"
  28. ```
  29. ## Quick Start
  30. ### Running with Claude Desktop
  31. You can make the server available in Claude Desktop either through the MCP CLI or by manually configuring Claude Desktop.
  32. #### Using MCP CLI
  33. Register the server with Claude Desktop:
  34. ```bash
  35. mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"
  36. ```
  37. #### Manual Configuration
  38. Alternatively, you can manually configure Claude Desktop:
  39. 1. Open your Claude Desktop configuration file:
  40. - macOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json`
  41. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  42. Create the file if it doesn't exist.
  43. 2. Add the server to the `mcpServers` section:
  44. ```json
  45. {
  46. "mcpServers": {
  47. "tree_sitter": {
  48. "command": "python",
  49. "args": [
  50. "-m",
  51. "mcp_server_tree_sitter.server"
  52. ]
  53. }
  54. }
  55. }
  56. ```
  57. Alternatively, if using uv or another package manager:
  58. ```json
  59. {
  60. "mcpServers": {
  61. "tree_sitter": {
  62. "command": "uv",
  63. "args": [
  64. "--directory",
  65. "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
  66. "run",
  67. "-m",
  68. "mcp_server_tree_sitter.server"
  69. ]
  70. }
  71. }
  72. }
  73. ```
  74. Note: Make sure to replace `/ABSOLUTE/PATH/TO/YOUR/PROJECT` with the actual absolute path to your project directory.
  75. 3. Save the file and restart Claude Desktop.
  76. 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.
  77. ### Configuring with Released Version
  78. 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:
  79. 1. Open your Claude Desktop configuration file (same location as above).
  80. 2. Add the tree-sitter server to the `mcpServers` section:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "tree_sitter": {
  85. "command": "uvx",
  86. "args": [
  87. "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
  88. "mcp-server-tree-sitter"
  89. ]
  90. }
  91. }
  92. }
  93. ```
  94. 3. Save the file and restart Claude Desktop.
  95. 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.
  96. ## State Persistence
  97. The MCP Tree-sitter Server maintains state between invocations. This means:
  98. - Projects stay registered until explicitly removed or the server is restarted
  99. - Parse trees are cached according to configuration settings
  100. - Language information is retained throughout the server's lifetime
  101. This persistence is maintained in-memory during the server's lifetime using singleton patterns for key components.
  102. ### Running as a standalone server
  103. There are several ways to run the server:
  104. #### Using the MCP CLI directly:
  105. ```bash
  106. python -m mcp run mcp_server_tree_sitter.server
  107. ```
  108. #### Using Makefile targets:
  109. ```bash
  110. # Show available targets
  111. make
  112. # Run the server with default settings
  113. make mcp-run
  114. # Show help information
  115. make mcp-run ARGS="--help"
  116. # Show version information
  117. make mcp-run ARGS="--version"
  118. # Run with custom configuration file
  119. make mcp-run ARGS="--config /path/to/config.yaml"
  120. # Enable debug logging
  121. make mcp-run ARGS="--debug"
  122. # Disable parse tree caching
  123. make mcp-run ARGS="--disable-cache"
  124. ```
  125. #### Using the installed script:
  126. ```bash
  127. # Run the server with default settings
  128. mcp-server-tree-sitter
  129. # Show help information
  130. mcp-server-tree-sitter --help
  131. # Show version information
  132. mcp-server-tree-sitter --version
  133. # Run with custom configuration file
  134. mcp-server-tree-sitter --config /path/to/config.yaml
  135. # Enable debug logging
  136. mcp-server-tree-sitter --debug
  137. # Disable parse tree caching
  138. mcp-server-tree-sitter --disable-cache
  139. ```
  140. ### Using with the MCP Inspector
  141. Using the MCP CLI directly:
  142. ```bash
  143. python -m mcp dev mcp_server_tree_sitter.server
  144. ```
  145. Or using the Makefile target:
  146. ```bash
  147. make mcp-dev
  148. ```
  149. You can also pass arguments:
  150. ```bash
  151. make mcp-dev ARGS="--debug"
  152. ```
  153. ## Usage
  154. ### Register a Project
  155. First, register a project to analyze:
  156. ```
  157. register_project_tool(path="/path/to/your/project", name="my-project")
  158. ```
  159. ### Explore Files
  160. List files in the project:
  161. ```
  162. list_files(project="my-project", pattern="**/*.py")
  163. ```
  164. View file content:
  165. ```
  166. get_file(project="my-project", path="src/main.py")
  167. ```
  168. ### Analyze Code Structure
  169. Get the syntax tree:
  170. ```
  171. get_ast(project="my-project", path="src/main.py", max_depth=3)
  172. ```
  173. Extract symbols:
  174. ```
  175. get_symbols(project="my-project", path="src/main.py")
  176. ```
  177. ### Search Code
  178. Search for text:
  179. ```
  180. find_text(project="my-project", pattern="function", file_pattern="**/*.py")
  181. ```
  182. Run tree-sitter queries:
  183. ```
  184. run_query(
  185. project="my-project",
  186. query='(function_definition name: (identifier) @function.name)',
  187. language="python"
  188. )
  189. ```
  190. ### Analyze Complexity
  191. ```
  192. analyze_complexity(project="my-project", path="src/main.py")
  193. ```
  194. ## Direct Python Usage
  195. While the primary intended use is through the MCP server, you can also use the library directly in Python code:
  196. ```python
  197. # Import from the API module
  198. from mcp_server_tree_sitter.api import (
  199. register_project, list_projects, get_config, get_language_registry
  200. )
  201. # Register a project
  202. project_info = register_project(
  203. path="/path/to/project",
  204. name="my-project",
  205. description="Description"
  206. )
  207. # List projects
  208. projects = list_projects()
  209. # Get configuration
  210. config = get_config()
  211. # Access components through dependency injection
  212. from mcp_server_tree_sitter.di import get_container
  213. container = get_container()
  214. project_registry = container.project_registry
  215. language_registry = container.language_registry
  216. ```
  217. ## Configuration
  218. Create a YAML configuration file:
  219. ```yaml
  220. cache:
  221. enabled: true # Enable/disable caching (default: true)
  222. max_size_mb: 100 # Maximum cache size in MB (default: 100)
  223. ttl_seconds: 300 # Cache entry time-to-live in seconds (default: 300)
  224. security:
  225. max_file_size_mb: 5 # Maximum file size to process in MB (default: 5)
  226. excluded_dirs: # Directories to exclude from processing
  227. - .git
  228. - node_modules
  229. - __pycache__
  230. allowed_extensions: # Optional list of allowed file extensions
  231. # - py
  232. # - js
  233. # Leave empty or omit for all extensions
  234. language:
  235. default_max_depth: 5 # Default max depth for AST traversal (default: 5)
  236. preferred_languages: # List of languages to pre-load at startup for faster performance
  237. - python # Pre-loading reduces latency for first operations
  238. - javascript
  239. log_level: INFO # Logging level (DEBUG, INFO, WARNING, ERROR)
  240. max_results_default: 100 # Default maximum results for search operations
  241. ```
  242. Load it with:
  243. ```
  244. configure(config_path="/path/to/config.yaml")
  245. ```
  246. ### Logging Configuration
  247. The server's logging verbosity can be controlled using environment variables:
  248. ```bash
  249. # Enable detailed debug logging
  250. export MCP_TS_LOG_LEVEL=DEBUG
  251. # Use normal informational logging (default)
  252. export MCP_TS_LOG_LEVEL=INFO
  253. # Only show warning and error messages
  254. export MCP_TS_LOG_LEVEL=WARNING
  255. ```
  256. For comprehensive information about logging configuration, please refer to the [logging documentation](docs/logging.md). For details on the command-line interface, see the [CLI documentation](docs/cli.md).
  257. ### About preferred_languages
  258. The `preferred_languages` setting controls which language parsers are pre-loaded at server startup rather than on-demand. This provides several benefits:
  259. - **Faster initial analysis**: No delay when first analyzing a file of a pre-loaded language
  260. - **Early error detection**: Issues with parsers are discovered at startup, not during use
  261. - **Predictable memory allocation**: Memory for frequently used parsers is allocated upfront
  262. By default, all parsers are loaded on-demand when first needed. For optimal performance, specify the languages you use most frequently in your projects.
  263. You can also configure specific settings:
  264. ```
  265. configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")
  266. ```
  267. Or use environment variables:
  268. ```bash
  269. export MCP_TS_CACHE_MAX_SIZE_MB=256
  270. export MCP_TS_LOG_LEVEL=DEBUG
  271. export MCP_TS_CONFIG_PATH=/path/to/config.yaml
  272. ```
  273. 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.
  274. Configuration values are applied in this order of precedence:
  275. 1. Environment variables (highest)
  276. 2. Values set via `configure()` calls
  277. 3. YAML configuration file
  278. 4. Default values (lowest)
  279. The server will look for configuration in:
  280. 1. Path specified in `configure()` call
  281. 2. Path specified by `MCP_TS_CONFIG_PATH` environment variable
  282. 3. Default location: `~/.config/tree-sitter/config.yaml`
  283. ## For Developers
  284. ### Diagnostic Capabilities
  285. The MCP Tree-sitter Server includes a diagnostic framework to help identify and fix issues:
  286. ```bash
  287. # Run diagnostic tests
  288. make test-diagnostics
  289. # CI-friendly version (won't fail the build on diagnostic issues)
  290. make test-diagnostics-ci
  291. ```
  292. 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](docs/diagnostics.md).
  293. ### Type Safety Considerations
  294. 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](docs/tree-sitter-type-safety.md) for important information about handling tree-sitter API variations.
  295. ## Available Resources
  296. The server provides the following MCP resources:
  297. - `project://{project}/files` - List all files in a project
  298. - `project://{project}/files/{pattern}` - List files matching a pattern
  299. - `project://{project}/file/{path}` - Get file content
  300. - `project://{project}/file/{path}/lines/{start}-{end}` - Get specific lines from a file
  301. - `project://{project}/ast/{path}` - Get the AST for a file
  302. - `project://{project}/ast/{path}/depth/{depth}` - Get the AST with custom depth
  303. ## Available Tools
  304. The server provides tools for:
  305. - Project management: `register_project_tool`, `list_projects_tool`, `remove_project_tool`
  306. - Language management: `list_languages`, `check_language_available`
  307. - File operations: `list_files`, `get_file`, `get_file_metadata`
  308. - AST analysis: `get_ast`, `get_node_at_position`
  309. - Code search: `find_text`, `run_query`
  310. - Symbol extraction: `get_symbols`, `find_usage`
  311. - Project analysis: `analyze_project`, `get_dependencies`, `analyze_complexity`
  312. - Query building: `get_query_template_tool`, `list_query_templates_tool`, `build_query`, `adapt_query`, `get_node_types`
  313. - Similar code detection: `find_similar_code`
  314. - Cache management: `clear_cache`
  315. - Configuration diagnostics: `diagnose_config`
  316. See [FEATURES.md](FEATURES.md) for detailed information about each tool's implementation status, dependencies, and usage examples.
  317. ## Available Prompts
  318. The server provides the following MCP prompts:
  319. - `code_review` - Create a prompt for reviewing code
  320. - `explain_code` - Create a prompt for explaining code
  321. - `explain_tree_sitter_query` - Explain tree-sitter query syntax
  322. - `suggest_improvements` - Create a prompt for suggesting code improvements
  323. - `project_overview` - Create a prompt for a project overview analysis
  324. ## Feedback & Community
  325. We'd love to hear how you're using mcp-server-tree-sitter and what would make it more useful for your workflow.
  326. - **Questions & Feature Requests**: [GitHub Discussions](https://github.com/wrale/mcp-server-tree-sitter/discussions)
  327. - **Bug Reports**: [GitHub Issues](https://github.com/wrale/mcp-server-tree-sitter/issues)
  328. ## License
  329. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.