grok-mcp

Use Grok as a peer code reviewer and rigorous second-opinion consultant inside Claude Code, Cursor, Cline, OpenClaw, and any other MCP host — talking to xAI's API directly (just an XAI_API_KEY, no install) or via the official Grok CLI.

grok-mcp (npm: grok-cli-mcp) is a Model Context Protocol server for Grok. It gives your primary agent (Claude, Cursor, etc.) four tools so it can delegate to Grok for high-quality second opinions and rigorous validation without leaving the session. As of v0.3.0 it talks to xAI's API directly — no grok binary required — and still supports the CLI for OAuth users:

• grok_review — structured diff review with per-dimension scores
• grok_challenge — thorough analysis for bugs, races, edge cases and security issues
• grok_consult — multi-turn consultation (caller owns history)
• grok_chat — one-shot questions

English | 繁體中文

Why grok-mcp?

Most "Grok MCP" packages expose Grok's chat/search/image capabilities so Claude can use Grok. grok-mcp lets your main coding agent (Claude/Cursor/…) ask Grok for a rigorous second opinion on its own work. A different model providing thorough review often catches issues that single-model loops miss.

What you get

Four tools, all stateless, all stdout-only:

Prerequisites

• Node.js ≥ 18
• A backend (the server picks one automatically — see Backends):
  • API mode (recommended, zero install): an XAI_API_KEY from console.x.ai. The server calls xAI's HTTP API directly — no extra binary needed.
  • CLI mode: the Grok CLI installed, used when no XAI_API_KEY is set:
    Terminal

    Copy

    curl -fsSL https://x.ai/cli/install.sh | bash
    

    Then authenticate with browser OAuth (run grok once interactively). See Authentication below.

Install

npm install -g grok-cli-mcp
# or use npx — no install needed
npx grok-cli-mcp

Why the npm name is grok-cli-mcp instead of grok-mcp? The bare grok-mcp name on npm was already taken by an unrelated project (a Grok HTTP-API integration). The brand, GitHub repo, and MCP server identity stay grok-mcp; only the npm install identifier is grok-cli-mcp — chosen to highlight that this server wraps the official Grok CLI.

Authentication

There are two auth methods, each tied to a backend:

Setting XAI_API_KEY switches the server to API mode, so you can keep your browser login for interactive grok use and use a key just for this MCP server via its env block:

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"],
      "env": {
        "XAI_API_KEY": "xai-...",
        "GROK_MCP_TIMEOUT": "600000"
      }
    }
  }
}

Treat the key file as a secret — it ends up in your MCP host's config (e.g. ~/.claude.json), which is plain JSON on disk.

Wire it into your MCP host

Claude Code

Recommended — use add-json so the env block parses cleanly:

claude mcp add-json -s user grok '{
  "command": "npx",
  "args": ["-y", "grok-cli-mcp"],
  "env": { "XAI_API_KEY": "xai-...", "GROK_MCP_TIMEOUT": "600000" }
}'

Why add-json not claude mcp add -e ...? The -e KEY=val flag is variadic and will greedily consume the server name as another env value if you pass more than one. add-json sidesteps that footgun entirely.

Or edit ~/.claude.json directly. Minimal (OAuth fallback):

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"]
    }
  }
}

Cursor

Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"]
    }
  }
}

Cline (VS Code)

Settings → Cline → MCP Servers:

{
  "grok": {
    "command": "npx",
    "args": ["-y", "grok-cli-mcp"]
  }
}

Claude Desktop (local, no hosting needed)

Claude Desktop still supports local stdio servers: Settings → Developer → Edit Config (claude_desktop_config.json), then paste the same JSON block as Claude Code above.

Claude Web / Claude Desktop connectors (remote, v0.4+)

Claude's Settings → Connectors → Add custom connector dialog needs an HTTPS URL, not a command — so deploy the bundled Streamable HTTP server and paste its URL:

# 1. Generate a path secret (keeps strangers from spending your xAI credits)
openssl rand -base64 32 | tr '+/' '-_'

# 2. Deploy anywhere that runs Node (Railway / Fly / Render / a VPS).
#    A multi-stage Dockerfile ships in the repo:
docker build -t grok-mcp . && docker run \
  -e XAI_API_KEY=xai-... \
  -e GROK_MCP_PATH_SECRET=<secret-from-step-1> \
  -p 3000:3000 grok-mcp

# ...or without Docker:
XAI_API_KEY=xai-... GROK_MCP_PATH_SECRET=<secret> npx -y -p grok-cli-mcp grok-mcp-http

Then add the connector in Claude with the URL:

https://your-host.example.com/mcp/<secret-from-step-1>

No OAuth needed — leave the Client ID/Secret fields blank. Claude only starts an OAuth flow if the server asks for it.

Remote-mode notes:

• Treat the URL as a credential. The path secret is what stands between the internet and your xAI bill. Rotate it by changing the env var.
• grok_review needs an explicit diff over HTTP — the server can't see your local repo, so auto git diff is disabled in remote mode.
• Keep GROK_MCP_TIMEOUT below your platform's request timeout (and disable scale-to-zero) — grok-4 reasoning can run for minutes.
• GET /health is available for platform health checks; see .env.example for all knobs (GROK_MCP_ALLOWED_HOSTS, GROK_MCP_CORS_ORIGINS, ...).

Any other MCP host

grok-mcp speaks plain stdio MCP. Point any client at npx -y grok-cli-mcp and it works. HTTP hosts can point at the remote endpoint above instead.

Tool reference

grok_chat

{ "prompt": "Explain consistent hashing in two sentences." }

Optional: model to override the default Grok model; timeout (seconds) to extend the per-call limit for long grok-4 reasoning. All four tools accept timeout.

grok_review

{ "base_ref": "main", "focus": "security" }

If diff is omitted, runs git diff <base_ref>...HEAD in cwd (defaults to your host's working directory). Returns a markdown review by default with verdict, per-dimension scores (correctness / readability / architecture / security / performance), and concrete fix-it items.

Pass "format": "json" to get machine-parseable output suitable for CI gating — see Use as a PR gate.

grok_consult

{
  "messages": [
    { "role": "system", "content": "You are a senior backend engineer." },
    { "role": "user", "content": "How would you cache this query?" },
    { "role": "assistant", "content": "Two options..." },
    { "role": "user", "content": "What's the failure mode of option 2?" }
  ]
}

The server is stateless — the caller passes the full thread each time. Most MCP hosts handle this naturally.

grok_challenge

{
  "code": "function transfer(from, to, amount) { from.balance -= amount; to.balance += amount; }",
  "context": "Node.js, called concurrently from HTTP handlers"
}

Returns severity-ranked issues (Critical / High / Medium / Low) with concrete reproductions and patches.

Configuration

Backends

The server can reach Grok two ways and chooses one at startup (it logs which to stderr):