/ 目录 / 演练场 / Tree-sitter MCP
● 社区 wrale ⚡ 即开即用

Tree-sitter MCP

作者 wrale · wrale/mcp-server-tree-sitter

将 Tree-sitter 接入 MCP——给 Claude 提供 AST 级别的访问能力,让它编辑某个函数,而不是匹配 47 个随机正则表达式。

tree-sitter-mcp 将 Tree-sitter 解析器封装为 MCP tool。不再让 Claude 在代码里 grep,而是给它提供 get_functionlist_symbolsfind_calls 等工具。agent 可以在 AST 层面做精准修改:「只重命名函数定义,而不是碰巧匹配到的字符串字面量。」

为什么要用

核心特性

实时演示

实际使用效果

tree-sitter-mcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "tree-sitter-mcp": {
      "command": "uvx",
      "args": [
        "mcp-server-tree-sitter"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "tree-sitter-mcp": {
      "command": "uvx",
      "args": [
        "mcp-server-tree-sitter"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "tree-sitter-mcp": {
      "command": "uvx",
      "args": [
        "mcp-server-tree-sitter"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "tree-sitter-mcp": {
      "command": "uvx",
      "args": [
        "mcp-server-tree-sitter"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "tree-sitter-mcp",
      "command": "uvx",
      "args": [
        "mcp-server-tree-sitter"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "tree-sitter-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-server-tree-sitter"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add tree-sitter-mcp -- uvx mcp-server-tree-sitter

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Tree-sitter MCP

重命名函数,同时不误改碰巧匹配的字符串

👤 做重构的开发者 ⏱ ~15 min intermediate

何时使用: 你想把 validateTokenverifyToken,但不想顺带改掉文档注释里「this validates token」这句话。

步骤
  1. 找到定义
    Use tree-sitter MCP. Find the definition of validateToken — function only, ignore strings and comments.✓ 已复制
    → 返回 AST 节点,含 file:line 及节点类型 'function_definition'
  2. 找到引用
    Find all call sites of validateToken — only identifier-resolution matches.✓ 已复制
    → 引用列表,字符串中无误报
  3. 重命名
    Rename to verifyToken everywhere it's a real reference. Show me the diff.✓ 已复制
    → diff 显示 N 处重命名,均在标识符位置

结果: 干净的重命名,不会碰注释、字符串或文档。

注意事项
  • 动态分发 / 反射导致遗漏 — 结合 semble 对动态用法做语义召回
搭配使用: filesystem · semble-mcp

精确获取函数体,为提取方法重构做准备

👤 整理长函数的工程师 ⏱ ~20 min intermediate

何时使用: 你想把函数的第 42-87 行提取为一个工具函数——要精确操作。

步骤
  1. 切片
    Show me the exact AST node for the for-loop at line 42 in handler.py.✓ 已复制
    → 返回循环节点及字节范围
  2. 提取
    Move that loop into a new function process_batch. Replace original with a call.✓ 已复制
    → 重构 diff 保留原始缩进和作用域

结果: 重构后一次编译通过。

注意事项
  • 捕获的变量未提升为参数 — 提取前让 Claude 先枚举自由变量

计算每个文件的代码复杂度指标

👤 工程管理者 / 技术债审计 ⏱ ~25 min intermediate

何时使用: 你需要一张复杂代码的热点地图。

步骤
  1. 遍历
    For every .py file under src/, count function defs and rough cyclomatic complexity using AST.✓ 已复制
    → 每个文件的数据表
  2. 排名
    Top 10 most complex functions — report file, line, name, score.✓ 已复制
    → 排名靠前的热点函数列表

结果: 有优先级的重构 backlog。

注意事项
  • 圈复杂度 ≠ 可读性 — 结合审阅者判断;指标只是起点

组合

与其他 MCP 搭配,撬动十倍杠杆

tree-sitter-mcp + semble-mcp

语义召回(semble)+ 结构精确定位(tree-sitter)

Use semble to find probable call sites, then tree-sitter to verify each is a real identifier.✓ 已复制
tree-sitter-mcp + filesystem

只读取 AST 推导出的行范围

Tree-sitter the function range, then filesystem to dump the exact bytes.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
parse_file path 获取文件的完整 AST free
list_symbols path, kind? 顶层符号清单 free
find_definition name, scope? 定位某个符号的定义位置 free
find_references name 安全重命名时查找调用点 free
get_node path, byte_range or line_range 精确切片节点用于重构 free

成本与限制

运行它的成本

API 配额
无——本地运行
每次调用 Token 数
100-1500
费用
免费
提示
切片节点,不要 dump 整个文件

安全

权限、密钥、影响范围

最小权限: Local file read
凭据存储:
数据出站:

故障排查

常见错误与修复

Language not supported

添加对应的 Tree-sitter 语法;查阅 README 中支持的语言列表

Parse errors on partial files

Tree-sitter 会恢复解析但会标记 ERROR 节点;忽略或在语法层面修复

Slow first run

语法编译只发生一次;后续运行会很快

替代方案

Tree-sitter MCP 对比其他方案

替代方案何时用它替代权衡
ast-grep需要 CLI 优先的结构化搜索替换工具作为 MCP 的集成度较低
Language servers (LSP)需要完整的类型解析,而不仅仅是语法分析配置更重;每种语言需要单独的 server

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills