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:
- Find code patterns based on syntax structure, not just text matching
- Search for specific programming constructs (functions, classes, imports, etc.)
- Write and test complex search rules using YAML configuration
- Debug and visualize AST structures for better pattern development
-
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:
Visualize the Abstract Syntax Tree structure of code snippets. Essential for understanding how to write effective search patterns.
Use cases:
- Debug why a pattern isn't matching
- Understand the AST structure of target code
- Learn ast-grep pattern syntax
Test ast-grep YAML rules against code snippets before applying them to larger codebases.
Use cases:
- Validate rules work as expected
- Iterate on rule development
- Debug complex matching logic
Search codebases using simple ast-grep patterns for straightforward structural matches.
Use cases:
- Find function calls with specific patterns
- Locate variable declarations
- Search for simple code constructs
Advanced codebase search using complex YAML rules that can express sophisticated matching criteria.
Use cases:
- Find nested code structures
- Search with relational constraints (inside, has, precedes, follows)
- Complex multi-condition searches
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:
- JavaScript/TypeScript
- Python
- Rust
- Go
- Java
- C/C++
- C#
- And many more...
- "Command not found" errors: Ensure ast-grep is installed and in your PATH
- No matches found: Try adding
stopBy: end
to relational rules - Pattern not matching: Use
dump_syntax_tree
to understand the AST structure - Permission errors: Ensure the server has read access to target directories
This is an experimental project. Issues and pull requests are welcome!
- ast-grep - The core structural search tool
- Model Context Protocol - The protocol this server implements
- FastMCP - The Python MCP framework used