Grok Build

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

这是一个轻量级进程包装器，不会重新实现 Agent 逻辑，也不会直接调用 xAI API——所有智能都由 grok CLI 提供。此服务增加的是忠实的参数构造、可靠的进程监管，以及格式整洁的 MCP 输出。

状态：0.2.2。 工具接口已完备。服务可在前台或后台以分离模式运行真正的无头 Grok Agent，在运行期间流式传输进度，按请求停止运行、审查 git 差异、在 Web 上研究问题、列出运行所创建的会话，并报告会话、用量和费用。请参阅 CHANGELOG.md 了解已发布的内容，以及 ROADMAP.md 了解曾考虑但最终未采用的内容。

进度

长时间运行的 Agent 会在执行过程中持续显示，而不是默默等待后只给出一大段文本。当客户端发送 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)

进度反映的是 Agent 正在做什么，而非它处于哪个阶段。推理和响应文本会合并处理，避免令牌流淹没客户端；工具调用则会在发生时报告。支持 resetTimeoutOnProgress 的客户端不会在运行中途超时。

未发送 progressToken 的客户端会使用成本更低的非流式路径，因此无需为此付费。

要求

• Grok Build CLI 1.0.0 或更高版本，且已完成身份验证（grok models 应能成功运行）
• Node.js 22 或更高版本

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

安装

Claude Code

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

-s user 会为你的整个账户注册服务，而不是仅限当前所在目录。不使用此选项时，作用范围仅限于当前项目；对于通用编码助手来说，这通常并非你想要的。结果就是下次在其他位置启动 Claude Code 时，服务会消失。

然后，在 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 -s user -- ~/.local/share/grok-build-mcp/node_modules/.bin/grok-build-mcp-server

权限

通过此服务启动的 Grok 默认以只读模式运行：使用 --permission-mode plan 和 --sandbox read-only。除非你明确允许，否则无法修改任何文件。

权限是注册服务时一次性设置的上限，而非每次调用时都会出现的提示。共有三个级别：

级别	--permission-mode	--sandbox	允许的操作
read-only（默认）	plan	read-only	读取和推理。不允许编辑
write	auto	workspace	编辑工作目录中的内容
full	bypassPermissions	off	无人值守，完全授权

沙盒设置不可协商，拒绝也不只是警告。在 write 模式下，运行无法写入 cwd 以外的位置；一旦工具调用遭到拒绝，整个运行就会结束：CLI 会报告 stopReason: cancelled，以 0 退出，并且只返回模型在遭到拒绝前说过的内容。此时服务会指出被拒绝的调用及其路径，因此不会误以为是模型主动放弃了。服务可以知道哪个调用失败，却无法知道 CLI 拒绝它的原因。如果运行必须写入其他位置（例如仓库外的报告），请将路径设为 cwd 内的位置，或使用 full。

write 使用 --permission-mode auto，而非 acceptEdits；实际表现取决于该标志的行为，而不是名称。无头运行的 Grok 没有人可以接受编辑，因此在 acceptEdits、dontAsk 和 default 模式下，所有文件修改都会遭到拒绝，运行也会随之终止；这在两种沙盒配置下都一样。auto 和 bypassPermissions 均可用；auto 的权限范围更窄，并且仍会拒绝写入工作区之外的位置，因此 full 确实是更高一级的权限，而非仅仅换个名称。

要允许 Grok 进行编辑：

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

只有在你已经以完全授权模式运行 MCP 客户端，并且希望委派的 Grok 运行也同样不受干预时，才使用 full。它会授予启动的 grok 进程与你相同的权限。

超出权限上限的调用会被拒绝，而非静默降级——如果运行被限制后报告成功，却什么都没改，反而不如明确报错。

环境变量

变量	默认值	用途
GROK_BINARY	grok	grok 可执行文件的路径
GROK_MCP_PERMISSION_CEILING	read-only	任何调用可请求的最高权限级别
GROK_MCP_DEFAULT_PERMISSION	read-only	调用未指定权限时使用的级别
GROK_MCP_DEFAULT_MODEL	grok-4.6	调用未指定模型时使用的模型。none 表示交由 CLI 决定
GROK_MCP_DEFAULT_EFFORT	high	调用未指定时使用的推理力度。none 表示交由 CLI 决定
GROK_MCP_TIMEOUT_MS	1800000	单次运行的最长时限
GROK_MCP_STATE_DIR	$XDG_STATE_HOME/grok-mcp	后台任务记录
GROK_MCP_MAX_CONCURRENT_RUNS	4	同时运行的后台任务数。off 表示不设上限
GROK_MCP_LOG_LEVEL	info	debug、info、warn、error。日志输出到 stderr
STRUCTURED_CONTENT_ENABLED	off	除 _meta 外，也输出 structuredContent

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

工具

工具	只读	用途
grok	由上限决定	运行无头 Grok Agent。支持提示词、会话恢复/继续/分叉、模型、力度、工具允许/拒绝列表
review	始终	审查 git 差异：工作树差异、与某个引用进行的 merge-base 差异，或单个提交
websearch	始终	在网上研究问题，并报告实际使用的搜索和来源
status	始终	轮询后台任务，或列出最近的任务
stop	否	终止后台任务的进程树
sessions	始终	列出、搜索并查找此计算机上的 Grok 会话
check	是	服务版本、解析后的二进制文件、grok version、身份验证、权限上限、运行默认值
help	是	透传 grok --help

review

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

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

目标可以是 uncommitted、base: "<ref>"（合并基点差异，因此分支后合入基分支的提交不会归到你名下），或 commit: "<sha>"。如果未指定目标，则会自动检测：分支领先时使用上游差异，否则使用工作树；并会说明选择了哪种方式，而不是默默猜测。

无论 GROK_MCP_PERMISSION_CEILING 允许什么，review 始终为只读。它不接受 permission、write 或 yolo 参数，因为让审查代码的操作去修改代码，绝不是用户想要的结果。

传入 structured: true，即可在 _meta.findings 中获取机器可读的审查结果（包含 severity、file、line、summary、rationale），并且这些结果会在你看到之前经过验证。

两种不同的问题可能会导致失败，系统会分别报告，而不会混为一谈：

• 运行未能完成——运行被中断，或结束时未生成审查结果。此时没有审查结果，因此调用会返回 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 模式下跨三个页面搜索了六次，成本是前者的 2.5 倍。

结果会告诉你实际查找了什么，而不只是模型写了什么：

[1 web search, 9 sources]

其中 _meta 包含 webSearches、webToolCalls、searchQueries、sources、sourceCount、pagesOpened 和 searchPerformed。这比听起来更重要。Grok 可以通过网页搜索或 X 进行检索；当网页不可用时，它会悄悄改用 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

长时间运行的 Agent 任务不必一直占用你的客户端。为 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，而已停止的任务永远不会结束——因此，系统会从 CLI 自己的会话存储中读取该 ID，而非重新构造。_meta.sessionIdSource 会告诉你 ID 的来源。如果同一目录中的两个运行任务都可能匹配，你会得到候选 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 可信发布：工作流会交换一个短期有效的 OIDC 令牌，而 npm 会自行生成来源证明。信任关系针对本仓库和此工作流的文件名注册，因此重命名 release.yml 会导致发布失败——而且 npm 只有在尝试发布时才会检查配置，届时出现的错误是 ENEEDAUTH，而不是任何能指出原因的信息。

许可证

MIT — 参见 LICENSE。