grok-mcp

MCP server that wraps the xAI Grok API. Lets Claude and other AI agents delegate thinking, planning, and real-time search to Grok.

Quick Start

One-liner to add to Claude Code on any device:

claude mcp add grok -e XAI_API_KEY=your-key -- npx -y @pkwadsy/grok-mcp

You need an xAI API key from console.x.ai.

Alternative: project config

Add to your project's .mcp.json:

{
  "mcpServers": {
    "grok": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pkwadsy/grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

Tools

ask_grok

Ask Grok a question with optional file context, web search, and X/Twitter search.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | yes | The question or task for Grok | | files | string[] | no | Files to include in context (see file syntax below) | | max_files | number | no | Override max file count (default 50) | | max_file_size | number | no | Override max per-file size in KB (default 32) | | system_prompt | string | no | Custom system prompt | | model | string | no | Model to use (default: grok-4.20-multi-agent) | | web_search | boolean | no | Web search, enabled by default | | x_search | boolean | no | Enable X/Twitter search |

check_files

Dry-run file resolution. Validates all files and shows sizes without calling Grok. If check_files passes, ask_grok will too.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | files | string[] | yes | Files to check (same syntax as ask_grok) | | max_files | number | no | Override max file count (default 50) | | max_file_size | number | no | Override max per-file size in KB (default 32) |

File syntax

Files are passed as an array of strings with compact syntax:

| Syntax | Description | |--------|-------------| | "src/index.ts" | Whole file | | "src/index.ts:10-30" | Lines 10 to 30 | | "src/index.ts:10" | Just line 10 | | "src/**/*.ts" | Glob pattern | | "large-file.ts:force" | Bypass per-file size limit | | "large-file.ts:1-100:force" | Combine line range with force |

Safety limits

| Limit | Default | Override | |-------|---------|----------| | Files per call | 50 | max_files param | | Per-file size | 32 KB | max_file_size param or :force suffix | | Total context | 256 KB | Hard cap, not overridable |

Available models

• grok-4.20-multi-agent — multi-agent mode, great for architecture and planning (default)
• grok-4.20-reasoning — flagship reasoning
• grok-4.20-non-reasoning — fast, no reasoning
• grok-4.1-fast-reasoning — cheaper reasoning
• grok-4.1-fast-non-reasoning — cheapest, fast

Examples

Ask with file context:

prompt: "Review this code for bugs"
files: ["src/index.ts", "src/utils.ts:20-50"]

Search the web:

prompt: "What happened in tech news today?"

Search X/Twitter:

prompt: "What are people saying about the new React release?"
x_search: true

Check files before asking:

files: ["src/**/*.ts"]

License

MIT