Ast Grep

What is Ast Grep?

Ast Grep is an experimental Model Context Protocol (MCP) server that gives AI assistants structural code search capabilities using ast-grep, an Abstract Syntax Tree (AST) pattern matching tool. It is designed for developers using MCP‑compatible clients like Cursor or Claude Desktop to analyze codebases by syntax structure rather than plain text.

How to use Ast Grep?

Install ast‑grep and uv, clone the repository, run uv sync, then configure your MCP client (Cursor or Claude Desktop) to run main.py with uv. Alternatively, run directly via uvx without cloning: uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server. Optionally set a custom ast‑grep config file using --config flag or AST_GREP_CONFIG environment variable.

Key features of Ast Grep

• Visualize AST structure with dump_syntax_tree
• Test YAML rules against code snippets with test_match_code_rule
• Simple pattern search with find_code
• Advanced rule‑based search with find_code_by_rule
• Supports dozens of languages including JavaScript, Python, Rust, Go, Java, C/C++, C#
• Configurable via custom sgconfig.yaml for rule behavior and custom languages

Use cases of Ast Grep

• Debug why an ast‑grep pattern isn't matching by inspecting the AST
• Validate and iterate on search rules before applying them to a full codebase
• Find all instances of a specific function call or variable declaration
• Search for complex nested code structures using relational constraints like inside, has, precedes, follows
• Develop and test multi‑condition YAML rules interactively with an AI assistant

FAQ from Ast Grep

What are the prerequisites to use Ast Grep?

You need ast‑grep installed (via brew, nix, or cargo), uv (Python package manager), and an MCP‑compatible client like Cursor or Claude Desktop.

How can I run Ast Grep without cloning the repository?

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

What languages does Ast Grep support?

Ast Grep supports many programming languages including JavaScript/TypeScript, Python, Rust, Go, Java, C/C++, C#, and more. Custom languages can be added via sgconfig.yaml.

How do I configure custom ast‑grep settings?

Provide a sgconfig.yaml file either via the --config command‑line argument or the AST_GREP_CONFIG environment variable.

What should I do if no matches are found?

Make sure ast‑grep is installed and in your PATH. For relational rules, try adding stopBy: end. Use dump_syntax_tree to understand the AST structure of your target code.