ast-grep-mcp

ast-grep-mcp

MCP server that exposes ast-grep (sg) as two tools for structural code search.

Prerequisites

Install sg (ast-grep CLI):

# via npm
npm i -g @ast-grep/cli

# via cargo
cargo install ast-grep

Verify: sg --version

Install & run

# from this directory
npm install
node src/index.js        # starts MCP server on stdio
# or via npx after publish:
# npx ast-grep-mcp

Tools

ast_search

Structural code search using an ast-grep pattern.

param	type	required	description
lang	string	yes	Language: js, ts, py, go, rust, java, …
pattern	string	yes	ast-grep pattern (e.g. console.log($MSG))
dir	string	no	Directory to search (default: .)

Returns: JSON array of { file, line, match, snippet }

Example prompt:

Use ast_search with lang=ts, pattern=console.log($MSG), dir=./src

ast_search_preset

Run a named code-smell preset.

param	type	required	description
name	enum	yes	One of the 5 presets below
dir	string	no	Directory to search (default: .)

Available presets:

name	what it finds
async-no-catch	await expressions — check for missing try/catch
hooks-missing-deps	useEffect(..., []) — empty deps may hide missing dependencies
route-no-auth	Express app.METHOD(path, handler) — routes that may lack auth middleware
sql-no-param	Template-literal SQL strings — potential injection risk
promise-no-return	new Promise(...) bodies — check all paths resolve/reject

Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}

Cursor mcp.json

.cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}

Or if you publish to npm:

{
  "mcpServers": {
    "ast-grep": {
      "command": "npx",
      "args": ["ast-grep-mcp"]
    }
  }
}

Pattern quick-reference

$VAR          – single node (any)
$$$NODES      – multiple nodes (spread)
`template $X` – template literal containing X
foo($A, $B)   – function call with two args

See ast-grep pattern syntax for full docs.