\n\n# grok-mcp\n\n[](https://www.npmjs.com/package/grok-cli-mcp)\n[](https://registry.modelcontextprotocol.io/)\n\n> 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](https://x.ai/news/grok-build-cli).\n\n`grok-mcp` (npm: [`grok-cli-mcp`](https://www.npmjs.com/package/grok-cli-mcp)) is a [Model Context Protocol](https://modelcontextprotocol.io) 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:\n\n- `grok_review` — structured diff review with per-dimension scores\n- `grok_challenge` — thorough analysis for bugs, races, edge cases and security issues\n- `grok_consult` — multi-turn consultation (caller owns history)\n- `grok_chat` — one-shot questions\n\nEnglish | [繁體中文](./README.zh-TW.md)\n\n## Why grok-mcp?\n\nMost \"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.\n\n## What you get\n\nFour tools, all stateless, all stdout-only:\n\n| Tool | Use it for |\n|------|------------|\n| `grok_chat` | One-shot prompt → Grok's reply |\n| `grok_review` | Pass a unified diff (or auto-grab `git diff main...HEAD`) and get a per-dimension code review |\n| `grok_consult` | Replay a message history for multi-turn — caller owns the thread |\n| `grok_challenge` | Rigorous analysis: ask Grok to surface bugs, race conditions, edge cases, and security issues |\n\n## Prerequisites\n\n- Node.js ≥ 18\n- A backend (the server picks one automatically — see [Backends](#backends)):\n - **API mode (recommended, zero install):** an `XAI_API_KEY` from [console.x.ai](https://console.x.ai). The server calls xAI's HTTP API directly — no extra binary needed.\n - **CLI mode:** the Grok CLI installed, used when no `XAI_API_KEY` is set:\n ```bash\n curl -fsSL https://x.ai/cli/install.sh | bash\n ```\n Then authenticate with browser OAuth (run `grok` once interactively). See [Authentication](#authentication) below.\n\n## Install\n\n```bash\nnpm install -g grok-cli-mcp\n# or use npx — no install needed\nnpx grok-cli-mcp\n```\n\n> **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**.\n\n## Authentication\n\nThere are two auth methods, each tied to a [backend](#backends):\n\n| Method | Backend | Best for | Rate limits |\n|--------|---------|----------|-------------|\n| **API key** (`XAI_API_KEY` env var) | API mode — no `grok` binary needed | MCP / CI / automation | Pay-per-call, no subscription cap |\n| **Browser OAuth** (`grok` interactive login) | CLI mode | Local interactive use | Subject to your grok.com plan tier |\n\nSetting `XAI_API_KEY` switches the server to [API mode](#backends), so you can keep your browser login for interactive `grok` use and use a key *just for this MCP server* via its env block:\n\n```json\n{\n \"mcpServers\": {\n \"grok\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"grok-cli-mcp\"],\n \"env\": {\n \"XAI_API_KEY\": \"xai-...\",\n \"GROK_MCP_TIMEOUT\": \"600000\"\n }\n }\n }\n}\n```\n\nTreat 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.\n\n## Wire it into your MCP host\n\n### Claude Code\n\nRecommended — use `add-json` so the env block parses cleanly:\n\n```bash\nclaude mcp add-json -s user grok '{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"grok-cli-mcp\"],\n \"env\": { \"XAI_API_KEY\": \"xai-...\", \"GROK_MCP_TIMEOUT\": \"600000\" }\n}'\n```\n\n> **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.\n\nOr edit `~/.claude.json` directly. Minimal (OAuth fallback):\n\n```json\n{\n \"mcpServers\": {\n \"grok\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"grok-cli-mcp\"]\n }\n }\n}\n```\n\n### Cursor\n\nCreate `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n \"mcpServers\": {\n \"grok\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"grok-cli-mcp\"]\n }\n }\n}\n```\n\n### Cline (VS Code)\n\nSettings → Cline → MCP Servers:\n\n```json\n{\n \"grok\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"grok-cli-mcp\"]\n }\n}\n```\n\n### Claude Desktop (local, no hosting needed)\n\nClaude Desktop still supports local stdio servers: **Settings → Developer → Edit Config** (`claude_desktop_config.json`), then paste the same JSON block as Claude Code above.\n\n### Claude Web / Claude Desktop connectors (remote, v0.4+)\n\nClaude'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:\n\n```bash\n# 1. Generate a path secret (keeps strangers from spending your xAI credits)\nopenssl rand -base64 32 | tr '+/' '-_'\n\n# 2. Deploy anywhere that runs Node (Railway / Fly / Render / a VPS).\n# A multi-stage Dockerfile ships in the repo:\ndocker build -t grok-mcp . && docker run \\\n -e XAI_API_KEY=xai-... \\\n -e GROK_MCP_PATH_SECRET= \\\n -p 3000:3000 grok-mcp\n\n# ...or without Docker:\nXAI_API_KEY=xai-... GROK_MCP_PATH_SECRET= npx -y -p grok-cli-mcp grok-mcp-http\n```\n\nThen add the connector in Claude with the URL:\n\n```\nhttps://your-host.example.com/mcp/\n```\n\nNo OAuth needed — leave the Client ID/Secret fields blank. Claude only starts an OAuth flow if the server asks for it.\n\nRemote-mode notes:\n\n- **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.\n- **`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.\n- **Keep `GROK_MCP_TIMEOUT` below your platform's request timeout** (and disable scale-to-zero) — grok-4 reasoning can run for minutes.\n- `GET /health` is available for platform health checks; see [`.env.example`](./.env.example) for all knobs (`GROK_MCP_ALLOWED_HOSTS`, `GROK_MCP_CORS_ORIGINS`, ...).\n\n### Any other MCP host\n\n`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.\n\n## Tool reference\n\n### `grok_chat`\n\n```json\n{ \"prompt\": \"Explain consistent hashing in two sentences.\" }\n```\n\nOptional: `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`.\n\n### `grok_review`\n\n```json\n{ \"base_ref\": \"main\", \"focus\": \"security\" }\n```\n\nIf `diff` is omitted, runs `git diff ...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.\n\nPass `\"format\": \"json\"` to get machine-parseable output suitable for CI gating — see [Use as a PR gate](#use-as-a-pr-gate-ci).\n\n### `grok_consult`\n\n```json\n{\n \"messages\": [\n { \"role\": \"system\", \"content\": \"You are a senior backend engineer.\" },\n { \"role\": \"user\", \"content\": \"How would you cache this query?\" },\n { \"role\": \"assistant\", \"content\": \"Two options...\" },\n { \"role\": \"user\", \"content\": \"What's the failure mode of option 2?\" }\n ]\n}\n```\n\nThe server is stateless — the caller passes the full thread each time. Most MCP hosts handle this naturally.\n\n### `grok_challenge`\n\n```json\n{\n \"code\": \"function transfer(from, to, amount) { from.balance -= amount; to.balance += amount; }\",\n \"context\": \"Node.js, called concurrently from HTTP handlers\"\n}\n```\n\nReturns severity-ranked issues (Critical / High / Medium / Low) with concrete reproductions and patches.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---------|---------|---------|\n| `XAI_API_KEY` | *(unset — falls back to OAuth)* | API key from [console.x.ai](https://console.x.ai). When set, the server uses [API mode](#backends) (direct HTTP) and bills pay-per-call with no subscription rate cap. See [Authentication](#authentication). |\n| `GROK_MCP_BACKEND` | `auto` | Which backend to use: `api` (direct HTTP), `cli` (shell out to `grok`), or `auto` (API when `XAI_API_KEY` is set, else CLI). See [Backends](#backends). |\n| `GROK_MCP_MODEL` | `grok-4` | Model used in API mode. (CLI mode reads `~/.grok/config.toml`.) |\n| `GROK_MCP_BASE_URL` | `https://api.x.ai/v1` | API base URL — point at a proxy or compatible gateway in API mode. |\n| `GROK_MCP_BIN` | `grok` | Path to the `grok` binary (CLI mode only) |\n| `GROK_MCP_TIMEOUT` | `300000` | Default per-call timeout in milliseconds |\n\n### Backends\n\nThe server can reach Grok two ways and chooses one at startup (it logs which to stderr):\n\n- **API mode** — calls xAI's OpenAI-compatible `/chat/completions` endpoint directly using Node's built-in `fetch`. No `grok` binary required, cleaner errors, pay-per-call. Selected when `XAI_API_KEY` is set, or forced with `GROK_MCP_BACKEND=api`.\n- **CLI mode** — shells out to the installed `grok` binary (supports browser OAuth). Selected when no `XAI_API_KEY` is set, or forced with `GROK_MCP_BACKEND=cli`.\n\nForce a mode with `GROK_MCP_BACKEND`. In API mode, set the model with `GROK_MCP_MODEL`; in CLI mode, model defaults live in `~/.grok/config.toml`.\n\n### Timeouts\n\ngrok-4 is a reasoning model and long prompts routinely take longer than two minutes. The server's default per-call limit is **300s (5 min)**. You can change it three ways:\n\n- **Per call** — pass `timeout` (seconds) to any tool: `{ \"prompt\": \"...\", \"timeout\": 600 }`.\n- **Per server** — set `GROK_MCP_TIMEOUT` (milliseconds) in the MCP server's env.\n- **Host side** — the MCP host has its *own* request timeout that can fire before the server's. If calls still time out after raising the above, raise the host limit too. In Claude Code that's `MCP_TIMEOUT` (server startup) and `MCP_TOOL_TIMEOUT` (per tool call), both in milliseconds.\n\nOn timeout the error includes any partial output Grok produced before the deadline, so you don't lose a near-complete answer.\n\n## Use as a PR gate (CI)\n\n`grok-mcp` ships a `grok-review-ci` bin **and** a composite GitHub Action so Grok can review every PR and fail the check on `block`.\n\nDrop this into `.github/workflows/grok-review.yml` in your repo:\n\n```yaml\nname: Grok review\non: { pull_request: { branches: [main] } }\npermissions: { contents: read, pull-requests: write }\njobs:\n grok:\n runs-on: ubuntu-latest\n if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}\n steps:\n - uses: actions/checkout@v4\n with: { fetch-depth: 0 }\n - uses: howardpen9/grok-mcp/.github/actions/grok-review@main\n with:\n xai-api-key: ${{ secrets.XAI_API_KEY }}\n gate-on: block # also accepts: block,request_changes\n # focus: security # optional\n # min-score: 6 # optional — fail any dimension below this\n```\n\nThe action posts a sticky PR comment with verdict + per-dimension scores + concrete blockers, and exits non-zero (failing the check) when the verdict matches `gate-on`. Full example with comments: [`examples/workflows/grok-review.yml`](./examples/workflows/grok-review.yml).\n\nWant JSON straight from the tool instead? Pass `format: \"json\"` to `grok_review` — same schema as the bin emits, suitable for any pipeline:\n\n```json\n{\n \"verdict\": \"block\",\n \"summary\": \"Unparameterised SQL query in src/db.ts.\",\n \"scores\": { \"correctness\": 4, \"readability\": 7, \"architecture\": 5, \"security\": 2, \"performance\": 8 },\n \"blockers\": [\n { \"severity\": \"critical\", \"title\": \"SQL injection\", \"file\": \"src/db.ts\", \"line\": 42,\n \"reason\": \"User input concatenated directly into the query.\",\n \"fix\": \"Use the parameterised form `db.query(sql, [userId])`.\" }\n ],\n \"notes\": []\n}\n```\n\n## Roadmap\n\n- **v0.1** — four stateless tools, stdio transport\n- **Discoverability push (v0.1.3, shipped)** — naming unification, MCP Registry, Smithery, glama.ai, stronger positioning. See [`docs/improvement-plan.md`](./docs/improvement-plan.md) and [`CHANGELOG.md`](./CHANGELOG.md).\n- **v0.2 (shipped)** — `grok_review` JSON mode + `grok-review-ci` bin + GitHub Action for PR gating.\n- **v0.3 (shipped)** — direct xAI API backend (no `grok` CLI required); `GROK_MCP_BACKEND` api/cli/auto.\n- **v0.4 (current)** — remote MCP mode: `grok-mcp-http` Streamable HTTP server for Claude Web / Claude Desktop custom connectors, with path-secret auth, Dockerfile, and `.env.example`.\n- **v0.5** — server-side session persistence so `grok_consult` can take a `conversation_id`\n- **v0.6** — streaming responses through MCP `progress` notifications; OAuth + per-user key store for shared hosted instances\n\n## Development\n\n```bash\ngit clone https://github.com/howardpen9/grok-mcp.git\ncd grok-mcp\nnpm install\nnpm test\nnpm run build\n```\n\n## Contact\n\nBug reports & feature requests → [GitHub issues](https://github.com/howardpen9/grok-mcp/issues).\nDMs welcome on X: [@0xHoward_Peng](https://x.com/0xHoward_Peng).\n\n## License\n\nMIT\n",
"bytes": 14042,
"sha": "4e19ad892e2c612dcfb863dffc9f853d2aa4b22dccbd98642a10269109cada3d",
"repo_slug": "howardpen9/grok-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_howardpen9_grok_mcp_16343816/readme"
}
![\"grok-mcp](\"./assets/social-preview.png\")
\n