This MCP server lets AI assistants perform structural code search and analysis using ast-grep AST pattern matching.
Dump syntax trees (cst, pattern, or ast format) for code snippets or patterns to debug and understand AST structure.
Test ast-grep YAML rules against code snippets to validate and refine rules before larger searches.
Find code in a project using simple ast-grep patterns, with text or JSON output and optional result limits.
Find code using powerful YAML rules for complex structural and relational queries (inside, has, precedes, follows, etc.).
Supports many programming languages (JavaScript, Python, Rust, Go, Java, C/C++, C#, and more) with language auto-detection from file extensions.
Supports custom ast-grep configuration via sgconfig.yaml and custom ast-grep command paths/environment variables.
Enables structural code search and analysis of codebases using Abstract Syntax Tree (AST) pattern matching to find code patterns, functions, classes, and programming constructs across multiple languages including JavaScript, TypeScript, Python, Rust, Go, Java, C/C++, and C#.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ast-grep MCP Server find all async functions in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Code Search MCP
Install ast-grep: Follow ast-grep installation guide
# macOS
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --lockedInstall uv: Python package manager
curl -LsSf https://astral.sh/uv/install.sh | shMCP-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-mcpInstall dependencies:
uv syncVerify ast-grep installation:
ast-grep --versionuvxYou can run the server directly from GitHub using uvx:
uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-serverThis is useful for quickly trying out the server without cloning the repository.
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": {}
}
}
}The MCP server supports using a custom sgconfig.yaml file to configure ast-grep behavior.
See the ast-grep configuration documentation for details on the config file format.
You can provide the config file in two ways (in order of precedence):
Command-line argument: --config /path/to/sgconfig.yaml
Environment variable: AST_GREP_CONFIG=/path/to/sgconfig.yaml
If ast-grep is not in PATH, or must be launched through another command, set
AST_GREP_PATH. The value can be an executable path or a command prefix:
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
"env": {
"AST_GREP_PATH": "uv run ast-grep"
}
}
}
}Other examples:
AST_GREP_PATH="/custom/path/to/ast-grep"
AST_GREP_PATH="npx ast-grep"
AST_GREP_PATH='"/path containing spaces/ast-grep"'
If unset, the command defaults to ast-grep.
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_treeVisualize 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_match_code_ruleTest 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
find_codeSearch codebases using simple ast-grep patterns for straightforward structural matches.
Parameters:
max_results: Limit number of complete matches returned (default: unlimited)
output_format: Choose between "text" (default, ~75% fewer tokens) or "json" (full metadata)
Text Output Format:
Found 2 matches:
path/to/file.py:10-15
def example_function():
# function body
return result
path/to/file.py:20-22
def another_function():
passUse cases:
Find function calls with specific patterns
Locate variable declarations
Search for simple code constructs
find_code_by_ruleAdvanced codebase search using complex YAML rules that can express sophisticated matching criteria.
Parameters:
max_results: Limit number of complete matches returned (default: unlimited)
output_format: Choose between "text" (default, ~75% fewer tokens) or "json" (full metadata)
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: endast-grep supports many programming languages including:
JavaScript/TypeScript
Python
Rust
Go
Java
C/C++
C#
And many more...
For a complete list of built-in supported languages, see the ast-grep language support documentation.
You can also add support for custom languages through the sgconfig.yaml configuration file. See the custom language guide for details.
"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
MCP Python SDK - The Python MCP framework used
Codemod MCP - Gives AI assistants tools like tree-sitter AST and node types, ast-grep instructions (YAML and JS ast-grep), and Codemod CLI commands to easily build, publish, and run ast-grep based codemods.
Dump code's syntax structure or dump a query's pattern structure.
This is useful to discover correct syntax kind and syntax tree structure. Call it when debugging a rule.
The tool requires three arguments: code, language and format. The first two are self-explanatory.
format is the output format of the syntax tree.
use format=cst to inspect the code's concrete syntax tree structure, useful to debug target code.
use format=pattern to inspect how ast-grep interprets a pattern, useful to debug pattern rule.
Internally calls: ast-grep run --pattern --lang --debug-query=
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code you need | |
| language | Yes | The language of the code. Supported: bash, c, cpp, csharp, css, elixir, go, haskell, html, java, javascript, json, jsx, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, tsx, typescript, yaml | |
| format | No | Code dump format. Available values: pattern, ast, cst | cst |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It does well by explaining the tool's internal implementation ('Internally calls: ast-grep run...'), which reveals it's a wrapper around a command-line tool. However, it doesn't mention potential side effects, error conditions, or output format details beyond the format parameter options.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with the core purpose, provides usage guidance, explains parameters with practical examples, and ends with implementation details. While slightly longer than minimal, every sentence adds value and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a debugging tool with 3 parameters and no output schema, the description provides good context about what the tool does, when to use it, and how parameters affect behavior. It could be more complete by describing the output format or potential error cases, but given the tool's relatively simple purpose and good parameter documentation, it's mostly sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3, but the description adds significant value by explaining the practical meaning of the format parameter options (cst for 'debug target code' and pattern for 'debug pattern rule'), which goes beyond the schema's technical enum values. It also clarifies that code and language are 'self-explanatory' and provides context about what the tool actually does with these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('dump code's syntax structure' and 'dump a query's pattern structure') and distinguishes it from sibling tools by specifying it's for debugging syntax/pattern discovery rather than finding or testing code. It explicitly mentions this is for 'debugging a rule' which differentiates it from find_code, find_code_by_rule, and test_match_code_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Call it when debugging a rule') and offers clear alternatives for different debugging scenarios with the format parameter (use format=cst for debugging target code, use format=pattern for debugging pattern rule). This gives the agent specific decision criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code in a project folder that matches the given ast-grep pattern.
Pattern is good for simple and single-AST node result.
For more complex usage, please use YAML by find_code_by_rule.
Internally calls: ast-grep run --pattern [--json]
Output formats:
text (default): Compact text format with file:line-range headers and complete match text Example: Found 2 matches:
path/to/file.py:10-15 def example_function(): # function body return result
path/to/file.py:20-22 def another_function(): pass
json: Full match objects with metadata including ranges, meta-variables, etc.
The max_results parameter limits the number of complete matches returned (not individual lines). When limited, the header shows "Found X matches (showing first Y of Z)".
Example usage: find_code(pattern="class $NAME", max_results=20) # Returns text format find_code(pattern="class $NAME", output_format="json") # Returns JSON with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| project_folder | Yes | The absolute path to the project folder. It must be absolute path. | |
| pattern | Yes | The ast-grep pattern to search for. Note, the pattern must have valid AST structure. | |
| language | No | The language of the code. Supported: bash, c, cpp, csharp, css, elixir, go, haskell, html, java, javascript, json, jsx, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, tsx, typescript, yaml. If not specified, will be auto-detected based on file extensions. | |
| max_results | No | Maximum results to return | |
| output_format | No | 'text' or 'json' | text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool internally calls 'ast-grep run', explains output formats (text and JSON) with examples, clarifies that 'max_results' limits complete matches (not lines), and shows how limited results are displayed. It covers execution, output, and limitations well, though it doesn't mention error handling or performance aspects like rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized, with clear sections for purpose, usage guidelines, internal details, output formats, and examples. It uses bullet points and examples effectively, though it could be slightly more concise by integrating some details (e.g., internal call info) more seamlessly. Every sentence adds value, but minor trimming is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage, behavior, and outputs in detail, compensating for the lack of annotations and output schema. However, it doesn't explicitly address potential errors (e.g., invalid patterns or paths) or prerequisites (e.g., tool installation), leaving a small gap in contextual coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, such as noting that the pattern is for 'simple and single-AST node result' and providing example usage with 'pattern' and 'max_results'. However, it doesn't significantly enhance understanding of parameters like 'project_folder' or 'language' beyond what the schema provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find code in a project folder that matches the given ast-grep pattern.' It specifies the verb ('Find'), resource ('code'), and scope ('project folder'), and distinguishes it from sibling tools by noting that 'find_code_by_rule' is for more complex usage. This is specific and avoids tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: 'Pattern is good for simple and single-AST node result. For more complex usage, please use YAML by `find_code_by_rule`.' It also mentions internal implementation details and includes example usage, clearly defining the context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code using ast-grep's YAML rule in a project folder.
YAML rule is more powerful than simple pattern and can perform complex search like find AST inside/having another AST.
It is a more advanced search tool than the simple find_code.
Tip: When using relational rules (inside/has), add stopBy: end to ensure complete traversal.
Internally calls: ast-grep scan --inline-rules [--json]
Output formats:
text (default): Compact text format with file:line-range headers and complete match text Example: Found 2 matches:
src/models.py:45-52 class UserModel: def init(self): self.id = None self.name = None
src/views.py:12 class SimpleView: pass
json: Full match objects with metadata including ranges, meta-variables, etc.
The max_results parameter limits the number of complete matches returned (not individual lines). When limited, the header shows "Found X matches (showing first Y of Z)".
Example usage: find_code_by_rule(yaml="id: x\nlanguage: python\nrule: {pattern: 'class $NAME'}", max_results=20) find_code_by_rule(yaml="...", output_format="json") # For full metadata
| Name | Required | Description | Default |
|---|---|---|---|
| project_folder | Yes | The absolute path to the project folder. It must be absolute path. | |
| yaml | Yes | The ast-grep YAML rule to search. It must have id, language, rule fields. | |
| max_results | No | Maximum results to return | |
| output_format | No | 'text' or 'json' | text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the internal implementation ('Internally calls: ast-grep scan'), output formats with detailed examples, how max_results works ('limits the number of complete matches'), and handling of limited results. It doesn't mention error conditions or performance characteristics, but covers most essential operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose statement, comparison to sibling tool, usage tip, implementation details, output formats with examples, parameter behavior explanation, and example usage. While comprehensive, some sentences could be more concise, and the example usage section is quite detailed but necessary for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, the description provides substantial context: purpose, differentiation from siblings, behavioral details, output format explanations with examples, and parameter usage guidance. It covers what the tool does, how to use it, and what to expect, though it doesn't document the exact structure of returned data beyond format descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter-specific information beyond the schema - it mentions YAML rule requirements ('must have id, language, rule fields') and provides example usage with parameters, but doesn't significantly enhance understanding of individual parameters. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find code using ast-grep's YAML rule in a project folder.' It specifies the verb ('Find'), resource ('code'), and method ('using ast-grep's YAML rule'), and explicitly distinguishes it from the sibling tool 'find_code' by stating it's 'more powerful' and 'more advanced.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It states it's 'more powerful than simple pattern' and 'a more advanced search tool than the simple `find_code`,' directly comparing it to a sibling tool. It also includes a tip for using relational rules and example usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test a code against an ast-grep YAML rule. This is useful to test a rule before using it in a project.
Internally calls: ast-grep scan --inline-rules --json --stdin
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code to test against the rule | |
| yaml | Yes | The ast-grep YAML rule to search. It must have id, language, rule fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by mentioning the internal call ('Internally calls: ast-grep scan --inline-rules <yaml> --json --stdin'), which hints at the tool's execution method and output format (JSON). However, it doesn't cover aspects like error handling, performance implications, or side effects, leaving gaps in behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, the second adds usage context, and the third provides internal implementation details. Every sentence earns its place by adding value without redundancy, making it efficient and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It explains the purpose and internal call but lacks details on output values, error cases, or integration with sibling tools. Without an output schema, the description should ideally hint at return types, but it only mentions JSON format indirectly, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both parameters ('code' and 'yaml'). The description doesn't add any parameter-specific semantics beyond what the schema provides, such as format details or examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate or enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Test a code against an ast-grep YAML rule.' It specifies the verb ('test') and resources ('code' and 'ast-grep YAML rule'), making the action clear. However, it doesn't explicitly differentiate from sibling tools like 'find_code_by_rule', which might have overlapping functionality, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'This is useful to test a rule before using it in a project.' This implies when to use the tool (for testing rules pre-deployment) but doesn't specify when not to use it or mention alternatives like sibling tools. The guidance is implied rather than explicit, lacking detailed comparisons or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools have mostly distinct purposes: dump_syntax_tree is for debugging syntax structures, find_code and find_code_by_rule are for searching code with different rule formats, and test_match_code_rule is for testing rules. However, find_code and find_code_by_rule could be confused as both search for code matches, though their descriptions clarify the pattern vs. YAML rule distinction.
All tool names follow a consistent snake_case pattern with clear verb_noun structures: dump_syntax_tree, find_code, find_code_by_rule, and test_match_code_rule. This makes them predictable and easy to understand at a glance.
With 4 tools, this server is well-scoped for ast-grep functionality. Each tool serves a specific role in code analysis and debugging, covering core operations without being overly sparse or bloated.
The toolset covers essential ast-grep operations: debugging syntax, searching with patterns and YAML rules, and testing rules. A minor gap is the lack of a tool for modifying or refactoring code based on matches, but the server's focus on analysis and testing is adequately covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ast-grep/ast-grep-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
