ast-grep-mcp
An experimental Model Context Protocol (MCP) server that provides AI assistants with powerful structural code search capabilities using ast-grep.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ast-grep/ast-grep-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ast-grep/ast-grep-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/ast-grep--ast-grep-mcp)HTML
<a href="/listings/ast-grep--ast-grep-mcp"><img src="/api/listings/ast-grep--ast-grep-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Clone this repository:
git clone https://github.com/ast-grep/ast-grep-mcp.git cd ast-grep-mcp
2. Install dependencies:
uv sync
3. Verify ast-grep installation:
ast-grep --version
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 270 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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`
- ### Custom ast-grep Command
- 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:
- ```json
- {
- "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`.
- ## 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
- - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - 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)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.