grok-mcp

grok-mcp

在 Claude Code、Cursor、Cline、OpenClaw 和其他任何 MCP 宿主中，将 Grok 用作同行代码评审者和严谨的第二意见顾问——可直接调用 xAI 的 API（只需设置 XAI_API_KEY，无需安装），也可通过官方 Grok CLI 使用。

grok-mcp（npm：grok-cli-mcp）是用于 Grok 的 Model Context Protocol 服务。它为你的主 Agent（Claude、Cursor 等）提供四种工具，可在不离开当前会话的情况下委托 Grok 提供高质量的第二意见和严谨验证。截至 v0.3.0，它可直接调用 xAI 的 API——无需 grok 二进制文件——同时仍支持 OAuth 用户使用 CLI：

• grok_review — 结构化差异评审，并为各个维度评分
• grok_challenge — 针对错误、竞态、边界情况和安全问题进行全面分析
• grok_consult — 多轮咨询（由调用方管理历史记录）
• grok_chat — 单次提问

English | 繁體中文

为什么选择 grok-mcp？

大多数 “Grok MCP” 软件包都会暴露 Grok 的聊天、搜索和图像功能，让 Claude 可以使用 Grok。grok-mcp 则让你的主编码 Agent（Claude/Cursor/…）就自身工作向 Grok 征求严谨的第二意见。由不同模型进行全面评审，往往能发现单模型循环遗漏的问题。

可用功能

四种工具，均为无状态，且只向 stdout 输出：

工具	用途
grok_chat	单次提示词 → Grok 的回复
grok_review	传入统一差异（或自动获取 git diff main...HEAD），并获取按维度划分的代码评审
grok_consult	重放消息历史以进行多轮交流——由调用方管理对话
grok_challenge	严谨分析：请 Grok 找出错误、竞态条件、边界情况和安全问题

前提条件

• Node.js ≥ 18
• 一个后端（服务会自动选择，详见后端）：
  • API 模式（推荐，无需安装）： 从 console.x.ai 获取 XAI_API_KEY。服务会直接调用 xAI 的 HTTP API——无需额外的二进制文件。
  • CLI 模式： 未设置 XAI_API_KEY 时使用，需安装 Grok CLI：

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

    然后通过浏览器 OAuth 完成身份验证（交互式运行一次 grok）。详见下文的身份验证。

安装

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

为什么 npm 包名是 grok-cli-mcp，而不是 grok-mcp？ npm 上的 grok-mcp 名称已被一个不相关的项目占用（一个 Grok HTTP API 集成）。品牌、GitHub 仓库和 MCP 服务标识仍为 grok-mcp；只有 npm 安装标识是 grok-cli-mcp——选择这个名称是为了突出该服务封装了官方 Grok CLI。

身份验证

有两种身份验证方式，分别对应一种后端：

方式	后端	适用场景	速率限制
API 密钥（XAI_API_KEY 环境变量）	API 模式——无需 grok 二进制文件	MCP / CI / 自动化	按调用付费，无订阅上限
浏览器 OAuth（交互式登录 grok）	CLI 模式	本地交互式使用	受 grok.com 套餐等级限制

设置 XAI_API_KEY 会将服务切换到 API 模式，因此你可以保留浏览器登录以交互式使用 grok，并通过服务的环境变量配置块仅为此 MCP 服务使用密钥：

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

请将密钥文件视为机密——它最终会写入 MCP 宿主的配置文件（例如 ~/.claude.json），该文件以纯 JSON 格式存储在磁盘上。

将其接入 MCP 宿主

Claude Code

推荐使用 add-json，以便环境变量块能够正常解析：

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

为什么不用 add-json，而用 claude mcp add -e ...？ -e KEY=val 标志支持可变参数，如果传入多个参数，就会贪婪地将服务名称也当作另一个环境变量值。add-json 则完全避免了这个问题。

也可以直接编辑 ~/.claude.json。最简配置（OAuth 回退）：

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

Cursor

创建 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

Cline（VS Code）

设置 → Cline → MCP Servers：

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

Claude Desktop（本地，无需托管）

Claude Desktop 仍支持本地 stdio 服务：Settings → Developer → Edit Config（claude_desktop_config.json），然后粘贴与上方 Claude Code 相同的 JSON 块。

Claude Web / Claude Desktop 连接器（远程，v0.4+）

Claude 的 Settings → Connectors → Add custom connector 对话框需要 HTTPS URL，而不是命令——因此请部署捆绑的 Streamable HTTP 服务，并粘贴其 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

然后在 Claude 中使用该 URL 添加连接器：

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

无需 OAuth——Client ID/Secret 字段留空即可。只有在服务要求时，Claude 才会启动 OAuth 流程。

远程模式说明：

• 请将 URL 视为凭据。 路径密钥是互联网与您的 xAI 账单之间的唯一屏障。更改环境变量即可轮换密钥。
• grok_review 通过 HTTP 使用时需要显式传入 diff——服务无法访问您的本地仓库，因此远程模式下禁用了自动 git diff。
• 将 GROK_MCP_TIMEOUT 设为低于平台请求超时时间的值（并禁用缩容至零）——grok-4 推理可能需要数分钟。
• 可使用 GET /health 进行平台健康检查；所有可配置项（GROK_MCP_ALLOWED_HOSTS、GROK_MCP_CORS_ORIGINS 等）请参阅 .env.example。

其他 MCP 宿主

grok-mcp 使用标准 stdio MCP。将任意客户端指向 npx -y grok-cli-mcp 即可使用。HTTP 宿主也可以指向上方的远程端点。

工具参考

grok_chat

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

可选：使用 model 覆盖默认 Grok 模型；使用 timeout（秒）延长单次调用的时限，以支持耗时较长的 grok-4 推理。四个工具都接受 timeout。

grok_review

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

如果省略 diff，则会在 cwd 中运行 git diff <base_ref>...HEAD（默认使用宿主的工作目录）。默认返回 Markdown 格式的评审结果，包含结论、各维度评分（正确性 / 可读性 / 架构 / 安全性 / 性能）以及具体的修复建议。

传入 "format": "json" 可获取适用于 CI 门禁的机器可解析输出——请参阅用作 PR 门禁。

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?" }
  ]
}

该服务无状态——调用方每次都要传入完整对话。大多数 MCP 宿主都能自然地处理这一点。

grok_challenge

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

返回按严重程度排序的问题（Critical / High / Medium / Low），并附带具体的复现步骤和补丁。

配置

环境变量	默认值	用途
XAI_API_KEY	(未设置 — 回退到 OAuth)	来自 console.x.ai 的 API 密钥。设置后，服务将使用 API 模式（直接 HTTP），按次付费，且没有订阅速率上限。请参阅身份验证。
GROK_MCP_BACKEND	auto	要使用的后端：api（直接 HTTP）、cli（调用 grok 命令）或 auto（设置了 XAI_API_KEY 时使用 API，否则使用 CLI）。请参阅后端。
GROK_MCP_MODEL	grok-4	API 模式下使用的模型。（CLI 模式读取 ~/.grok/config.toml。）
GROK_MCP_BASE_URL	https://api.x.ai/v1	API 基础 URL——在 API 模式下可指向代理或兼容的网关。
GROK_MCP_BIN	grok	grok 二进制文件的路径（仅限 CLI 模式）
GROK_MCP_TIMEOUT	300000	单次调用的默认超时时间，单位为毫秒

后端

服务器可以通过两种方式访问 Grok，并在启动时选择其中一种（会将所选方式记录到 stderr）：

• API 模式 — 使用 Node 内置的 fetch，直接调用 xAI 兼容 OpenAI 的 /chat/completions 端点。无需 grok 二进制文件，错误信息更简洁，按次付费。设置 XAI_API_KEY 时会选择此模式，也可以通过 GROK_MCP_BACKEND=api 强制选择。
• CLI 模式 — 调用已安装的 grok 二进制文件（支持浏览器 OAuth）。未设置 XAI_API_KEY 时会选择此模式，也可以通过 GROK_MCP_BACKEND=cli 强制选择。

通过 GROK_MCP_BACKEND 强制指定模式。在 API 模式下，通过 GROK_MCP_MODEL 设置模型；在 CLI 模式下，模型默认值位于 ~/.grok/config.toml。

超时

grok-4 是推理模型，处理较长的提示词时经常需要超过两分钟。服务器默认的单次调用时限为 300s（5 分钟）。你可以通过以下三种方式更改：

• 单次调用 — 向任意工具传入 timeout（秒）：{ "prompt": "...", "timeout": 600 }。
• 单个服务 — 在 MCP 服务的环境变量中设置 GROK_MCP_TIMEOUT（毫秒）。
• 宿主端 — MCP 宿主有自己的请求超时时限，可能会早于服务端触发。如果提高上述时限后调用仍然超时，也请提高宿主端的时限。在 Claude Code 中，这两个值分别是 MCP_TIMEOUT（服务启动）和 MCP_TOOL_TIMEOUT（单次工具调用），单位均为毫秒。

发生超时时，错误中会包含 Grok 在截止时间前生成的部分输出，因此不会丢失接近完成的回答。

将其用作 PR 门禁（CI）

grok-mcp 附带 grok-review-ci 二进制文件和一个复合 GitHub Action，因此 Grok 可以审查每个 PR，并在结果为 block 时使检查失败。

将以下内容添加到仓库中的 .github/workflows/grok-review.yml：

name: Grok review
on: { pull_request: { branches: [main] } }
permissions: { contents: read, pull-requests: write }
jobs:
  grok:
    runs-on: ubuntu-latest
    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: howardpen9/grok-mcp/.github/actions/grok-review@main
        with:
          xai-api-key: ${{ secrets.XAI_API_KEY }}
          gate-on: block      # also accepts: block,request_changes
          # focus: security   # optional
          # min-score: 6      # optional — fail any dimension below this

该 Action 会发布一条置顶 PR 评论，其中包含判定结果、各维度评分和具体阻碍项；当判定结果与 gate-on 匹配时，会以非零状态码退出（使检查失败）。带评论的完整示例：examples/workflows/grok-review.yml。

想直接从工具获取 JSON？向 grok_review 传入 format: "json" 即可 — 输出结构与该二进制文件生成的结构相同，适用于任何流水线：

{
  "verdict": "block",
  "summary": "Unparameterised SQL query in src/db.ts.",
  "scores": { "correctness": 4, "readability": 7, "architecture": 5, "security": 2, "performance": 8 },
  "blockers": [
    { "severity": "critical", "title": "SQL injection", "file": "src/db.ts", "line": 42,
      "reason": "User input concatenated directly into the query.",
      "fix": "Use the parameterised form `db.query(sql, [userId])`." }
  ],
  "notes": []
}

路线图

• v0.1 — 四个无状态工具，stdio 传输
• 功能发现推进（v0.1.3，已发布） — 统一命名、MCP Registry、Smithery、glama.ai、更鲜明的定位。参见 docs/improvement-plan.md 和 CHANGELOG.md。
• v0.2（已发布） — grok_review JSON 模式 + grok-review-ci 二进制文件 + 用于 PR 门禁的 GitHub Action。
• v0.3（已发布） — 直接使用 xAI API 的后端（无需 grok CLI）；GROK_MCP_BACKEND 支持 api/cli/auto。
• v0.4（当前） — 远程 MCP 模式：grok-mcp-http Streamable HTTP 服务，用于 Claude Web / Claude Desktop 自定义连接器，支持路径密钥身份验证，并提供 Dockerfile 和 .env.example。
• v0.5 — 服务端会话持久化，让 grok_consult 可以接收 conversation_id
• v0.6 — 通过 MCP progress 通知流式传输响应；为共享托管实例提供 OAuth + 按用户区分的密钥存储

开发

git clone https://github.com/howardpen9/grok-mcp.git
cd grok-mcp
npm install
npm test
npm run build

联系方式

漏洞报告和功能请求 → GitHub 议题。 欢迎在 X 上私信： @0xHoward_Peng。

许可证

MIT