Content
# ast-grep MCP Server
An experimental [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with powerful structural code search capabilities using [ast-grep](https://ast-grep.github.io/).
## Overview
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
## Prerequisites
1. **Install ast-grep**: Follow [ast-grep installation guide](https://ast-grep.github.io/guide/quick-start.html#installation)
```bash
# macOS
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --locked
```
2. **Install uv**: Python package manager
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
3. **MCP-compatible client**: Such as Cursor, Claude Desktop, or other MCP clients
## Installation
1. Clone this repository:
```bash
git clone https://github.com/ast-grep/ast-grep-mcp.git
cd ast-grep-mcp
```
2. Install dependencies:
```bash
uv sync
```
3. Verify ast-grep installation:
```bash
ast-grep --version
```
## Running with `uvx`
You can run the server directly from GitHub using `uvx`:
```bash
uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server
```
This is useful for quickly trying out the server without cloning the repository.
## Configuration
### For Cursor
Add to your MCP settings (usually in `.cursor-mcp/settings.json`):
```json
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
"env": {}
}
}
}
```
### For Claude Desktop
Add to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"ast-grep": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
"env": {}
}
}
}
```
### Custom ast-grep Configuration
The MCP server supports using a custom `sgconfig.yaml` file to configure ast-grep behavior.
See the [ast-grep configuration documentation](https://ast-grep.github.io/guide/project/project-config.html) for details on the config file format.
You can provide the config file in two ways (in order of precedence):
1. **Command-line argument**: `--config /path/to/sgconfig.yaml`
2. **Environment variable**: `AST_GREP_CONFIG=/path/to/sgconfig.yaml`
## Usage
This repository includes comprehensive ast-grep rule documentation in [ast-grep.mdc](https://github.com/ast-grep/ast-grep-mcp/blob/main/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.
## Features
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:**
- Debug why a pattern isn't matching
- Understand the AST structure of target code
- Learn ast-grep pattern syntax
### 🧪 `test_match_code_rule`
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
### 🎯 `find_code`
Search 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():
pass
```
**Use cases:**
- Find function calls with specific patterns
- Locate variable declarations
- Search for simple code constructs
### 🚀 `find_code_by_rule`
Advanced 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
## Usage Examples
### Basic Pattern Search
Use Query:
> Find all console.log statements
AI will generate rules like:
```yaml
id: find-console-logs
language: javascript
rule:
pattern: console.log($$$)
```
### Complex Rule Example
User Query:
> Find async functions that use await
AI will generate rules like:
```yaml
id: async-with-await
language: javascript
rule:
all:
- kind: function_declaration
- has:
pattern: async
- has:
pattern: await $EXPR
stopBy: end
```
## Supported Languages
ast-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](https://ast-grep.github.io/reference/languages.html).
You can also add support for custom languages through the `sgconfig.yaml` configuration file. See the [custom language guide](https://ast-grep.github.io/guide/project/project-config.html#languagecustomlanguage) for details.
## Troubleshooting
### Common Issues
1. **"Command not found" errors**: Ensure ast-grep is installed and in your PATH
2. **No matches found**: Try adding `stopBy: end` to relational rules
3. **Pattern not matching**: Use `dump_syntax_tree` to understand the AST structure
4. **Permission errors**: Ensure the server has read access to target directories
## Contributing
This is an experimental project. Issues and pull requests are welcome!
## Related Projects
- [ast-grep](https://ast-grep.github.io/) - The core structural search tool
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol this server implements
- [FastMCP](https://github.com/pydantic/fastmcp) - The Python MCP framework used
- [Codemod MCP](https://docs.codemod.com/model-context-protocol) - 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.
[](https://mseep.ai/app/ast-grep-ast-grep-mcp)
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors