AST MCP Server

How to use

Connect your MCP client to the server and choose the analysis tool you need. Use the four main tools to explore and search code: dump_syntax_tree to inspect AST structures, test_match_code_rule to validate your YAML rules, find_code for straightforward pattern searches, and find_code_by_rule for complex, multi-condition searches.

Typical workflows include: writing an ast-grep YAML rule to describe a pattern, testing it on a small code sample with test_match_code_rule, and then applying it to larger codebases with find_code_by_rule or find_code to surface exact matches. Visualize the AST to refine patterns before expanding scope.

How to install

Prerequisites: install ast-grep, install uv, and ensure you have an MCP-compatible client.

Install ast-grep and related tooling and verify the installation.

# macOS (example)
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --locked

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

# verify
ast-grep --version

Run the server with uvx

Run the MCP server directly from a live source using uvx for quick testing without cloning locally.

uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server

Configuration

Configure each MCP client to connect to the server using stdio mode. You run the server locally via uv with a specific directory and entry script.

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

Cursor configuration example

Add this MCP server configuration to your Cursor settings to enable ast-grep MCP integration.

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

Claude Desktop configuration example

Add this MCP server configuration to enable ast-grep integration in Claude Desktop.

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

Custom ast-grep configuration

You can use a custom sgconfig.yaml to configure ast-grep behavior. Provide the config file path either via a command-line argument or an environment variable.

# Example usage with a config file path
AST_GREP_CONFIG=/path/to/sgconfig.yaml

Usage examples

Use the tools to perform targeted searches. For example, dump_syntax_tree helps you understand the AST, while find_code searches for simple structural patterns and find_code_by_rule handles complex, multi-condition queries. When writing your own rules, reference the available rule patterns and test incrementally.

Troubleshooting

Common issues include missing command errors, no matches, or permission problems. Ensure the server runs in an environment with access to target directories and that the command path is correct. Use dump_syntax_tree to verify AST structure when patterns don’t match.

Notes

This server is experimental and intended for AI-assisted code search and analysis using AST pattern matching. You can iterate on patterns, test rules, and visualize AST structures to improve search accuracy before applying rules to larger codebases.

dump_syntax_tree

Visualize the Abstract Syntax Tree for code snippets to understand structure and aid rule creation.

test_match_code_rule

Test ast-grep YAML rules against code snippets to validate behavior before applying to larger projects.

find_code

Search codebases for simple AST-based patterns with optional result formats.

find_code_by_rule

Perform complex searches using YAML rules to express nested, relational, and multi-condition queries.