Getting started with AST MCP Server in 5 minutes

AST MCP Server gives your AI coding agent compiler-aware context for TypeScript and JavaScript projects. This guide walks you through installation, configuration, and your first query — in under 5 minutes.

Prerequisites

• Node.js 22.13.0 or higher
• An AI coding agent that supports MCP (Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI, or GitHub Copilot CLI)

Step 1: Install globally

Run this command in your terminal:

npm install --global ast-mcp-server --ignore-scripts

The --ignore-scripts flag is recommended for security. The package is pure JavaScript with no native addons.

Step 2: Run the setup wizard

AST MCP Server includes a setup command that configures everything automatically:

ast-tool setup

This will detect your project structure and generate the correct MCP configuration.

Step 3: Add to your MCP config

If you prefer manual configuration, add this entry to your agent's MCP config file:

{
  "mcpServers": {
    "ast-mcp-server": {
      "command": "ast-mcp-server"
    }
  }
}

The config file location varies by agent:

• Claude Code: ~/.claude/mcp.json
• Codex CLI: ~/.codex/mcp.json
• Gemini CLI: ~/.gemini/mcp.json

Step 4: Verify the connection

Start your agent and ask it to use AST MCP Server:

Use ast_get_project_status to check the current project

You should see a response with your project's TypeScript configuration, file count, and symbol index status.

What you can do now

With AST MCP Server connected, your agent can search for symbols, get precise source, find all references, and analyze impact before making changes.

Troubleshooting

Agent can't find the server: Make sure ast-mcp-server is in your PATH. Run which ast-mcp-server to verify.

No symbols found: Run ast-tool validate in your project directory to check the index status.

Slow first query: The first query builds the symbol index. Subsequent queries use the cache and are much faster.