An experimental Model Context Protocol (MCP) server that provides AI assistants with powerful structural code search capabilities using ast-grep.
This MCP server enables AI assistants (like Cursor, Claude Desktop, etc.) to search and analyze codebases using Abstract Syntax Tree (AST) pattern matching rather than simple text-based search. By leveraging ast-grep's structural search capabilities, AI can:
Install ast-grep: Follow ast-grep installation guide
# macOS
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --locked
Install uv: Python package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
MCP-compatible client: Such as Cursor, Claude Desktop, or other MCP clients
Clone this repository:
git clone https://github.com/ast-grep/ast-grep-mcp.git
cd ast-grep-mcp
Install dependencies:
uv sync
Verify ast-grep installation:
ast-grep --version
Add to your MCP settings (usually in .cursor-mcp/settings.json
):
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
"env": {}
}
}
}
Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
"env": {}
}
}
}
This repository includes comprehensive ast-grep rule documentation in ast-grep.mdc. The documentation covers all aspects of writing effective ast-grep rules, from simple patterns to complex multi-condition searches.
You can add it to your cursor rule or Claude.md, and attach it when you need AI agent to create ast-grep rule for you.
The prompt will ask LLM to use MCP to create, verify and improve the rule it creates.
The server provides four main tools for code analysis:
dump_syntax_tree
Visualize the Abstract Syntax Tree structure of code snippets. Essential for understanding how to write effective search patterns.
Use cases:
test_match_code_rule
Test ast-grep YAML rules against code snippets before applying them to larger codebases.
Use cases:
find_code
Search codebases using simple ast-grep patterns for straightforward structural matches.
Use cases:
find_code_by_rule
Advanced codebase search using complex YAML rules that can express sophisticated matching criteria.
Use cases:
Use Query:
Find all console.log statements
AI will generate rules like:
id: find-console-logs
language: javascript
rule:
pattern: console.log($$$)
User Query:
Find async functions that use await
AI will generate rules like:
id: async-with-await
language: javascript
rule:
all:
- kind: function_declaration
- has:
pattern: async
- has:
pattern: await $EXPR
stopBy: end
ast-grep supports many programming languages including:
stopBy: end
to relational rulesdump_syntax_tree
to understand the AST structureThis is an experimental project. Issues and pull requests are welcome!
{ "mcpServers": { "ast-grep-mcp": { "command": "uv", "args": [ "--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories