ast-grep

by ast-grep

14 stars

758 downloads

Not rated

GitHub

About

Bridges to the ast-grep code search tool for finding code patterns in projects using abstract syntax tree matching, enabling efficient code analysis and refactoring tasks.

Details

Author: ast-grep
Repository: ast-grep/ast-grep-mcp
GitHub stars: 14
Downloads: 758
License: MIT License
Categories: Developer Tools, Productivity, File Management, AI, Search, Infrastructure, Project Management, Other
Tags: #integration

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name ast-grep

Command (node, npx, python, etc.) uv
Arguments
- Argument 1 --directory
- Argument 2 /absolute/path/to/ast-grep-mcp
- Argument 3 run
- Argument 4 main.py
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

From the repository

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.

You can run the server directly from GitHub using uvx:

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.

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):

1. Command-line argument: --config /path/to/sgconfig.yaml
2. Environment variable: AST_GREP_CONFIG=/path/to/sgconfig.yaml

`dump_syntax_tree`

Visualize the Abstract Syntax Tree structure of code snippets. Essential for understanding how to write effective search patterns.

`test_match_code_rule`

Test ast-grep YAML rules against code snippets before applying them to larger codebases.

`find_code`

Search codebases using simple ast-grep patterns for straightforward structural matches. Parameters: max_results (optional integer), output_format (optional string)

`find_code_by_rule`

Advanced codebase search using complex YAML rules that can express sophisticated matching criteria. Parameters: max_results (optional integer), output_format (optional string)

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "--directory",
        "/absolute/path/to/ast-grep-mcp",
        "run",
        "main.py"
    ],
    "command": "uv"
}

Macos

{
    "env": [],
    "args": [
        "--directory",
        "/absolute/path/to/ast-grep-mcp",
        "run",
        "main.py"
    ],
    "command": "uv"
}

Windows

{
    "env": [],
    "args": [
        "--directory",
        "/absolute/path/to/ast-grep-mcp",
        "run",
        "main.py"
    ],
    "command": "uv"
}

An experimentalModel 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

curl -LsSf https://astral.sh/uv/install.sh | sh

MCP-compatible client: Such as Cursor, Claude Desktop, or other MCP clients

git clone https://github.com/ast-grep/ast-grep-mcp.git cd ast-grep-mcp

You can run the server directly from GitHub usinguvx:

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.

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 customsgconfig.yamlfile to configure ast-grep behavior. See theast-grep configuration documentationfor 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

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.

- 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.

- Validate rules work as expected
- Iterate on rule development
- Debug complex matching logic

Search codebases using simple ast-grep patterns for straightforward structural matches.

- max_results: Limit number of complete matches returned (default: unlimited)
- output_format: Choose between"text"(default, ~75% fewer tokens) or"json"(full metadata)

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

- 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.

- max_results: Limit number of complete matches returned (default: unlimited)
- output_format: Choose between"text"(default, ~75% fewer tokens) or"json"(full metadata)

- Find nested code structures
- Search with relational constraints (inside, has, precedes, follows)
- Complex multi-condition searches

id: find-console-logs language: javascript rule: pattern: console.log($$$)

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...

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 thesgconfig.yamlconfiguration file. See the custom language guidefor details.
- "Command not found" errors: Ensure ast-grep is installed and in your PATH
- No matches found: Try addingstopBy: endto relational rules
- Pattern not matching: Usedump_syntax_treeto 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
- 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.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

A stateful LSP runtime for AI agents: warm language server sessions with 50+ tools for go-to-definition, find-references, diagnostics, rename, and more across 30+ languages.

AI-powered code quality analysis to detect best practice violations, security issues, and architectural problems in real-time.

MCP server that gives coding agents program-analysis primitives — data flow, call graphs, taint analysis — so they reason from ground truth instead of grep-and-guess. (same as the GitHub About — keeps your messaging consistent across the web).

An MCP service that equips your workspace with a complete set of AI-accessible development tools for reading, editing, executing, and managing code.

A development tool for real-time debugging, code quality monitoring, and AI insights for React/Next.js applications.

Visual Studio extension with 20 Roslyn-powered MCP tools for AI assistants. Semantic code navigation, symbol search, inheritance, call graphs, safe rename, build/test.

A VS Code extension that provides real-time diagnostic problems like errors and warnings via the Model Context Protocol.

A server for detecting critical performance issues in code, providing concise analysis and output.

An MCP server that runs PHPStan static analysis on PHP code — analyze files at a configurable rule level and memory limit, with support for PHPStan Pro, directly from your MCP client.

A server for code analysis using Tree-sitter, with context management capabilities.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

{
    "mcpServers": {
        "ast-grep": {
            "env": {},
            "args": [
                "--directory",
                "/absolute/path/to/ast-grep-mcp",
                "run",
                "main.py"
            ],
            "command": "uv"
        }
    }
}

About

Details

Jump to

Setting up with Highlight

From the repository

dump_syntax_tree

test_match_code_rule

find_code

find_code_by_rule

Claude Desktop / Cursor

Linux

Macos

Windows

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`dump_syntax_tree`

`test_match_code_rule`

`find_code`

`find_code_by_rule`