Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ast-grep--ast-grep-mcp/badge.svg)](/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

i

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)

  1. # ast-grep MCP Server
  2. 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/).
  3. ## Overview
  4. 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:
  5. - Find code patterns based on syntax structure, not just text matching
  6. - Search for specific programming constructs (functions, classes, imports, etc.)
  7. - Write and test complex search rules using YAML configuration
  8. - Debug and visualize AST structures for better pattern development
  9. ## Prerequisites
  10. 1. **Install ast-grep**: Follow [ast-grep installation guide](https://ast-grep.github.io/guide/quick-start.html#installation)
  11. ```bash
  12. # macOS
  13. brew install ast-grep
  14. nix-shell -p ast-grep
  15. cargo install ast-grep --locked
  16. ```
  17. 2. **Install uv**: Python package manager
  18. ```bash
  19. curl -LsSf https://astral.sh/uv/install.sh | sh
  20. ```
  21. 3. **MCP-compatible client**: Such as Cursor, Claude Desktop, or other MCP clients
  22. ## Installation
  23. 1. Clone this repository:
  24. ```bash
  25. git clone https://github.com/ast-grep/ast-grep-mcp.git
  26. cd ast-grep-mcp
  27. ```
  28. 2. Install dependencies:
  29. ```bash
  30. uv sync
  31. ```
  32. 3. Verify ast-grep installation:
  33. ```bash
  34. ast-grep --version
  35. ```
  36. ## Running with `uvx`
  37. You can run the server directly from GitHub using `uvx`:
  38. ```bash
  39. uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server
  40. ```
  41. This is useful for quickly trying out the server without cloning the repository.
  42. ## Configuration
  43. ### For Cursor
  44. Add to your MCP settings (usually in `.cursor-mcp/settings.json`):
  45. ```json
  46. {
  47. "mcpServers": {
  48. "ast-grep": {
  49. "command": "uv",
  50. "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
  51. "env": {}
  52. }
  53. }
  54. }
  55. ```
  56. ### For Claude Desktop
  57. Add to your Claude Desktop MCP configuration:
  58. ```json
  59. {
  60. "mcpServers": {
  61. "ast-grep": {
  62. "command": "uv",
  63. "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
  64. "env": {}
  65. }
  66. }
  67. }
  68. ```
  69. ### Custom ast-grep Configuration
  70. The MCP server supports using a custom `sgconfig.yaml` file to configure ast-grep behavior.
  71. See the [ast-grep configuration documentation](https://ast-grep.github.io/guide/project/project-config.html) for details on the config file format.
  72. You can provide the config file in two ways (in order of precedence):
  73. 1. **Command-line argument**: `--config /path/to/sgconfig.yaml`
  74. 2. **Environment variable**: `AST_GREP_CONFIG=/path/to/sgconfig.yaml`
  75. ### Custom ast-grep Command
  76. If `ast-grep` is not in `PATH`, or must be launched through another command, set
  77. `AST_GREP_PATH`. The value can be an executable path or a command prefix:
  78. ```json
  79. {
  80. "mcpServers": {
  81. "ast-grep": {
  82. "command": "uv",
  83. "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
  84. "env": {
  85. "AST_GREP_PATH": "uv run ast-grep"
  86. }
  87. }
  88. }
  89. }
  90. ```
  91. Other examples:
  92. - `AST_GREP_PATH="/custom/path/to/ast-grep"`
  93. - `AST_GREP_PATH="npx ast-grep"`
  94. - `AST_GREP_PATH='"/path containing spaces/ast-grep"'`
  95. If unset, the command defaults to `ast-grep`.
  96. ## Usage
  97. 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.
  98. 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.
  99. The prompt will ask LLM to use MCP to create, verify and improve the rule it creates.
  100. ## Features
  101. The server provides four main tools for code analysis:
  102. ### 🔍 `dump_syntax_tree`
  103. Visualize the Abstract Syntax Tree structure of code snippets. Essential for understanding how to write effective search patterns.
  104. **Use cases:**
  105. - Debug why a pattern isn't matching
  106. - Understand the AST structure of target code
  107. - Learn ast-grep pattern syntax
  108. ### 🧪 `test_match_code_rule`
  109. Test ast-grep YAML rules against code snippets before applying them to larger codebases.
  110. **Use cases:**
  111. - Validate rules work as expected
  112. - Iterate on rule development
  113. - Debug complex matching logic
  114. ### 🎯 `find_code`
  115. Search codebases using simple ast-grep patterns for straightforward structural matches.
  116. **Parameters:**
  117. - `max_results`: Limit number of complete matches returned (default: unlimited)
  118. - `output_format`: Choose between `"text"` (default, ~75% fewer tokens) or `"json"` (full metadata)
  119. **Text Output Format:**
  120. ```
  121. Found 2 matches:
  122. path/to/file.py:10-15
  123. def example_function():
  124. # function body
  125. return result
  126. path/to/file.py:20-22
  127. def another_function():
  128. pass
  129. ```
  130. **Use cases:**
  131. - Find function calls with specific patterns
  132. - Locate variable declarations
  133. - Search for simple code constructs
  134. ### 🚀 `find_code_by_rule`
  135. Advanced codebase search using complex YAML rules that can express sophisticated matching criteria.
  136. **Parameters:**
  137. - `max_results`: Limit number of complete matches returned (default: unlimited)
  138. - `output_format`: Choose between `"text"` (default, ~75% fewer tokens) or `"json"` (full metadata)
  139. **Use cases:**
  140. - Find nested code structures
  141. - Search with relational constraints (inside, has, precedes, follows)
  142. - Complex multi-condition searches
  143. ## Usage Examples
  144. ### Basic Pattern Search
  145. Use Query:
  146. > Find all console.log statements
  147. AI will generate rules like:
  148. ```yaml
  149. id: find-console-logs
  150. language: javascript
  151. rule:
  152. pattern: console.log($$$)
  153. ```
  154. ### Complex Rule Example
  155. User Query:
  156. > Find async functions that use await
  157. AI will generate rules like:
  158. ```yaml
  159. id: async-with-await
  160. language: javascript
  161. rule:
  162. all:
  163. - kind: function_declaration
  164. - has:
  165. pattern: async
  166. - has:
  167. pattern: await $EXPR
  168. stopBy: end
  169. ```
  170. ## Supported Languages
  171. ast-grep supports many programming languages including:
  172. - JavaScript/TypeScript
  173. - Python
  174. - Rust
  175. - Go
  176. - Java
  177. - C/C++
  178. - C#
  179. - And many more...
  180. For a complete list of built-in supported languages, see the [ast-grep language support documentation](https://ast-grep.github.io/reference/languages.html).
  181. 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.
  182. ## Troubleshooting
  183. ### Common Issues
  184. 1. **"Command not found" errors**: Ensure ast-grep is installed and in your PATH
  185. 2. **No matches found**: Try adding `stopBy: end` to relational rules
  186. 3. **Pattern not matching**: Use `dump_syntax_tree` to understand the AST structure
  187. 4. **Permission errors**: Ensure the server has read access to target directories
  188. ## Contributing
  189. This is an experimental project. Issues and pull requests are welcome!
  190. ## Related Projects
  191. - [ast-grep](https://ast-grep.github.io/) - The core structural search tool
  192. - [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol this server implements
  193. - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - The Python MCP framework used
  194. - [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.
  195. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ast-grep-ast-grep-mcp-badge.png)](https://mseep.ai/app/ast-grep-ast-grep-mcp)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.