grok-build-mcp-server

一个 MCP stdio 服务器，它将 Grok Build CLI（grok）作为工具暴露出来，供 Claude Code、Cursor、VS Code 或任何其他 MCP 客户端调用。

Claude Code  ──stdio/MCP──▶  grok-build-mcp-server  ──spawn──▶  grok CLI  ──▶  xAI API

它是一个轻量级进程包装器。它不重新实现代理逻辑，也不直接与 xAI API 通信——所有智能都保留在 grok CLI 中。这个服务器增加的是忠实的参数构建、健壮的进程监督以及干净的 MCP 格式输出。

状态：0.2.2。 工具表面已完整。该服务器在前台或后台分离模式下运行真正的无头 Grok 代理，在运行时流式传输进度，按请求停止运行，审查 git 差异，在网络上研究问题，列出这些运行创建的会话，并报告会话、使用情况和成本。请参阅 CHANGELOG.md 了解已发布的内容，以及 ROADMAP.md 了解已考虑和拒绝的内容。

进度

长时间运行的代理在运行时是可见的，而不是静默等待后出现一堵文本墙。当您的客户端发送 progressToken 时，服务器使用 --output-format streaming-json 运行 Grok，并为每个事件转发一个通知：

#5  list_dir .
#6  read_file README.md
#7  read_file — completed
#8  thinking: the user asked me to list files, read README.md, then …
#10 writing: DONE
#11 finished: end_turn (2 turns)

进度跟踪的是代理正在做什么，而不是它处于哪个阶段。推理和响应文本被合并，因此令牌流不会淹没您的客户端，而工具调用会在发生时报告。支持 resetTimeoutOnProgress 的客户端不会在运行中途超时。

不发送 progressToken 的客户端将使用更便宜的非流式路径，并且无需为此付出任何代价。

Related MCP server: Claude Code MCP Bridge

要求

• Grok Build CLI 1.0.0 或更新版本，已认证（grok models 应成功）

• Node.js 22 或更新版本

如果 grok 不在您的 PATH 中，请在注册服务器时将 GROK_BINARY 设置为其完整路径。

安装

Claude Code

claude mcp add grok-build -- npx -y grok-build-mcp-server

然后，在 Claude Code 中：

> use the grok-build check tool

check 报告已解析的二进制文件、CLI 版本、是否已认证以及活动的权限上限。如果一切正常，其余功能将正常工作。

任何其他 MCP 客户端

该服务器通过 stdio 使用 MCP 协议，并且不接受任何自己的参数：

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

VS Code 和 Cursor 接受本页顶部的安装徽章，这些徽章携带的正是该配置。

从 MCP Registry 安装的客户端将此服务器识别为 io.github.Nuruvala/grok-build-mcp-server。注册表条目与 npm 版本相同的标签发布，并指向相同的包。

如果 npx 找不到服务器

npx 首先将裸包名解析为本地项目。如果您的 MCP 客户端的工作目录是此仓库的检出——或任何其他 package.json 名为 grok-build-mcp-server 的项目——那么 npx -y grok-build-mcp-server 会运行本地入口点，找不到它，并以 command not found 失败。将其安装到自己的目录并注册该路径：

npm install --prefix ~/.local/share/grok-build-mcp grok-build-mcp-server
claude mcp add grok-build -- ~/.local/share/grok-build-mcp/node_modules/.bin/grok-build-mcp-server

权限

通过此服务器启动的 Grok 运行默认是只读的：--permission-mode plan 配合 --sandbox read-only。在您明确允许之前，无法修改您的文件。

权限是一个上限，在注册服务器时设置一次，而不是每次调用时提示。三个级别：

要让 Grok 进行编辑：

claude mcp add grok-build \
  -e GROK_MCP_PERMISSION_CEILING=write \
  -e GROK_MCP_DEFAULT_PERMISSION=write \
  -- npx -y grok-build-mcp-server

仅当您已经以完全批准模式运行 MCP 客户端，并且希望委托的 Grok 运行同样无人值守时，才使用 full。它授予生成的 grok 进程与您相同的权限。

请求超过上限的调用将被拒绝，而不是静默降级——一个被限制的运行会报告成功但实际未做任何更改，这比一个明确的错误更糟糕。

环境变量

Grok 自身的变量（XAI_API_KEY、GROK_HOME、GROK_DISABLE_AUTOUPDATER）会原封不动地传递给子进程。

工具

review

差异在进程内收集并嵌入到提示中，因此模型无需花费轮次重新发现它要审查的内容。

> review my working tree with grok-build
> review the diff against origin/main

目标是 uncommitted、base: "<ref>"（一个合并基础差异，因此您在分支之后落在基础分支上的提交不会归因于您），或 commit: "<sha>"。如果未指定，它会自动检测：当您的分支领先时使用上游差异，否则使用工作树——并且它会说明选择了哪个，而不是静默猜测。

review 始终是只读的，无论 GROK_MCP_PERMISSION_CEILING 允许什么。它不接受 permission、write 或 yolo 参数，因为审查代码时编辑被审查的代码从来都不是想要的。

传递 structured: true 以获取机器可读的发现（severity、file、line、summary、rationale），这些发现位于 _meta.findings 中，并在您看到之前经过验证。

两种不同的事情可能出错，它们会被不同地报告，而不是混为一谈：

• 运行从未完成——它被中断，或结束而未产生发现。没有审查，因此调用是 isError: true，并且 _meta.findingsComplete 为 false。正文首先说明原因，引用 CLI 自身的理由，并指出适合实际原因的修复方法。

• 运行完成但其输出无法验证。 调用仍然成功，返回原始文本加上 _meta.parseError——降级的审查胜过失败的审查。

您永远不会得到的是模型编造出的看似合理的发现。--json-schema 约束模型发出的每条消息，因此当它仍在读取时，它无法说“我正在工作”，除非以发现的形式——如果不加检查，它确实会这样做。该模式携带一个必需的 status 字段，以将该叙述排除在结果之外，并且永远不会通过模式匹配从部分响应中挽救任何内容。

对大型目标的结构化审查确实会以这种方式失败，且频率不低。这种失败是设计上的响亮。

一个试图使用 shell 的审查会被拒绝，而不是被终止。在无头模式下，一个不可批准的工具请求会取消整个运行，而 CLI 仍然以 0 退出，因此 review 直接拒绝 shell 和编辑工具——模型被告知“不”，并完成其审查，而不是在句子中间死亡。

websearch

> websearch: what changed in the latest Bun release?
> search the web for how Postgres handles advisory lock contention, in depth

numResults（1–50）和 searchDepth（basic 或 full）塑造提示——grok CLI 没有针对这两者的标志，并且这两个参数也不假装有。它们确实有效：同一个问题在 basic 下进行了一次搜索，跨越两个页面，而在 full 下进行了六次搜索，跨越三个页面，成本是前者的两倍半。

结果告诉您实际查找了什么，而不仅仅是模型写了什么：

[1 web search, 9 sources]

其中 _meta 携带 webSearches、webToolCalls、searchQueries、sources、sourceCount、pagesOpened 和 searchPerformed。这比听起来更重要。Grok 可以通过网络搜索或 X 进行研究，当网络不可用时，它会静默地使用第二种方式——自信地回答，引用 x.com，成功退出。散文部分无法让您区分。因此，一个搜索了 X 而不是网络的运行会在其第一行说明，并单独报告 xSearches，而一个没有任何返回的运行是一个错误，而不是来自模型自身记忆的看似自信的答案：

No search ran. The answer below is the model's own prior knowledge, not current sources.

searchPerformed 意味着来源返回了——而不是尝试了搜索。一个开始但从未返回，或返回空结果集的搜索，会被如实报告。

与 review 类似，websearch 始终为只读，不接受 permission、write 或 yolo 参数。它从不传递 --disable-web-search。

后台运行、status 和 stop

长时间运行的代理不必占用你的客户端。向 grok、review 或 websearch 传递 background: true，调用会立即返回一个 runId，同时一个分离的工作进程将任务运行至完成：

> have grok refactor the parser in the background
> status
> status the run from a minute ago and wait 30s for it
> stop that run

运行属于机器，而非此服务器：即使你的 MCP 客户端断开连接、服务器重启或关闭编辑器，它也会继续运行。记录保存在 GROK_MCP_STATE_DIR 下，每个运行对应一个目录。

对已完成运行的 status 返回与同步调用相同的结果——相同的文本、相同的元数据、相同的错误标志。后台是工具调用的传输方式，而非另一种实现。当运行处于活动状态时，你可以获取其状态、已用时间、两个进程 ID 以及进度日志的尾部；waitMs 最多阻塞两分钟，并在进度通知到达时转发它们。超时等待不是错误。

两种不诚实的情况被设计排除。工作进程不再存在的运行会被报告为 abandoned 而非仍在运行——机器重启或某些东西杀死了它。提前完成的运行也会被标记为：

mfk2p1x9-3ac71f0b  completed (cut off: cancelled)  grok  4m 12s  refactor the parser

在获得 runId 之前仍会进行验证：超过 GROK_MCP_PERMISSION_CEILING 的请求，或一对矛盾的会话标志，会被拒绝为失败的调用，而不是被接受然后在无人监控的进程中失败。

stop 提前结束运行。它向工作进程的整个进程组（工作进程及其生成的 grok 进程）发送 SIGTERM 信号，如果不够则发送 SIGKILL。停止已完成的运行不是错误，停止在调用到达前刚刚完成的运行也不是错误。

无法杀死进程树的停止会被报告为失败，而非已停止的运行。 如果没有可发送信号的对象，或杀死被拒绝，或进程树在 SIGKILL 后仍然存活，运行会保持 running 状态，调用返回一个包含 pid 的错误。一个 cancelled 记录与一个活动进程并存，这会是更整洁的答案，但也是无用的。

你在运行中途停止的通常已经产生了一些值得保留的内容，部分结果和会话 ID 都会被保留：

Stopped run msxji60o-8f5e27c4 (grok, ran 20s).
Signalled SIGTERM to process group 1703005; the tree exited.

The run was cancelled mid-flight, but it recorded a session before it ended:
  grok -r 01a010e2-478c-73d2-bce9-23552245c64d

Grok 仅在运行到达终点时报告会话 ID，而停止的运行永远不会到达终点——因此该 ID 是从 CLI 自身的会话存储中读取的，而非重建的。_meta.sessionIdSource 告诉你你拥有的是哪种。如果同一目录中的两个运行都可能匹配，你会得到候选 ID 且没有恢复命令：恢复错误的会话会继续别人的工作。

sessions

每次 Grok 运行都会在磁盘上留下一个会话，此服务器报告的每个会话 ID 都可以稍后恢复——从任何目录，由你在终端中或通过另一个工具调用。

> list my recent grok sessions
> what grok sessions did I run in this repo?
> find the grok session about the rate limiter

会话从 $GROK_HOME/sessions（默认为 ~/.grok/sessions）读取，这是 CLI 自身的存储，因此它们能在此服务器、你的 MCP 客户端以及你的机器重启后继续存在。传递 id 获取单个会话，query 对标题、首个提示和 ID 进行不区分大小写的搜索，cwd 限定到一个项目，limit 限制列表数量。

刚刚完成的运行还没有标题——Grok 稍后会填充它们（如果有的话）——因此行会回退到会话的第一个提示，titleSource 告诉你正在查看的是哪个。每一行都带有 resumeCommand，每个 grok 和 review 结果也是如此：

grok -r 01a00c8d-970c-7531-8a12-31dac582c22b

搜索仅限本地。grok sessions search 还会查询远程索引；此工具不会，因此仅存在于服务器端的会话不会出现。

开发

npm install
npm run build          # tsc -> dist/
npm run dev            # tsx src/index.ts
npm test               # node --test via tsx
npm run test:coverage  # same, with enforced coverage floors
npm run lint
npm run typecheck
npm run format

• docs/api-reference.md — 每个工具的参数、结果文本、_meta 键以及每个键被设置的确切条件。

• docs/security.md — 注册此服务器授权了什么，每个权限级别实际授予了什么，以及什么离开了你的机器。

• docs/engineering.md — 代码编写方式：架构、函数式 TypeScript 规则、错误和效果纪律、测试和覆盖率策略、提交工作流。

• CLAUDE.md — 项目背景以及此服务器依赖的已验证的 grok CLI 行为。

• ROADMAP.md — 里程碑、验收标准以及经过评估并被拒绝的想法。

发布

在 package.json 中提升 version，将 CHANGELOG.md 的 Unreleased 部分移到新版本标题下，提交，然后：

git tag -a v0.2.0 -m v0.2.0 && git push origin v0.2.0

.github/workflows/release.yml 运行完整门控，如果标签和 package.json 不一致则拒绝发布，将打包的 tarball 安装到临时目录，并对安装的二进制文件执行真实的 initialize，然后发布 同一个文件 并创建 GitHub 发布。

没有需要管理的发布凭据。认证是 npm trusted publishing：工作流交换一个短期 OIDC 令牌，npm 自行生成来源证明。信任是针对此仓库和此工作流的 文件名 注册的，因此重命名 release.yml 会破坏发布——而 npm 直到尝试发布时才会检查配置，此时的症状是 ENEEDAUTH，而不是任何能指出原因的信息。

许可证

MIT — 参见 LICENSE。