dump_syntax_treeLABSCO SUMMARY
The debugging tools are the point: you can see the AST and test the rule before the search.
Structural search fails silently when the pattern does not match the tree, and that is where most of the time goes. dump_syntax_tree and test_match_code_rule turn that into a two-step loop, and the repository ships ast-grep.mdc — rule documentation you can attach to your assistant so it writes the YAML for you.
What it is
An MCP server over ast-grep, giving structural search across a codebase through AST pattern matching rather than regular expressions.
What you get
- find_code — search with a simple ast-grep pattern, with max_results and output_format
- find_code_by_rule — search with a full YAML rule, for relational constraints like inside, has, precedes and follows
- test_match_code_rule — run a rule against a snippet before turning it loose on the repository
- dump_syntax_tree — see the AST of a snippet, which is how you work out why a pattern is not matching
- Text output by default, which the project reports as roughly 75% fewer tokens than the JSON form; JSON is available when you want the full metadata
- Whatever languages ast-grep supports, plus custom ones added through sgconfig.yaml
Requirements
ast-grep installed and on your PATH — via Homebrew, nix or cargo — and uv. Run it from GitHub with uvx, or clone and point the client at main.py. If ast-grep is not on PATH, set AST_GREP_PATH to the executable or a command prefix; a custom config goes in AST_GREP_CONFIG or the --config argument.
Setup effort
One command — uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server
USE CASES
01
Finding a call pattern text search keeps missing
Write the pattern against the syntax instead of the characters, so formatting and whitespace stop mattering.
02
Working out why a pattern matches nothing
Dump the AST for the code you expected to match and compare it against what you wrote.
03
Searching for a nested structure
Express it as a YAML rule with relational constraints, then run it across the repository.
04
Checking a rule before you trust it
Run it against a snippet first — cheaper than reading a wrong result set from the whole codebase.
4 tools
Listed in project docs. Your client may show a different list.
test_match_code_rulefind_codefind_code_by_ruleBEFORE YOU INSTALL
What to know first
Tools you get
4 tools named in the project's documentation.
Requires
- ast-grep on PATH (brew install ast-grep, or cargo install ast-grep --locked)
- uv on PATH
- Python 3.13 or later
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
Setup
TERMINAL
git clone https://github.com/ast-grep/ast-grep-mcp.git
cd ast-grep-mcp
uv syncuvx
TERMINAL
uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-serverMCP Clients
Cursor, Claude Desktop
JSON
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_AST_GREP_MCP>",
"run",
"main.py"
],
"env": {}
}
}
}<YOUR_PATH_TO_AST_GREP_MCP> is the full path of the folder the git clone above created. If you run the uvx command instead, there is no clone for this path to point at.
