内容
# Grok-MCP
一个最小的本地MCP服务器（stdio），允许Claude Desktop或Claude Code将编码任务委派给**Grok Build**，该服务器以无头模式运行，作为子代理。
该服务器的设计用于监督代理：结果与git进行核实（没有虚假的“文件已修改”），失败是诚实的失败，长时间任务作为后台作业运行，每个结果都带有机器可读的`structuredContent`负载。
## 工具
### `grok_task`
| 输入 | 必需 | 描述 |
| --- | --- | --- |
| `prompt` | 是 | Grok Build的编码任务 |
| `cwd` | 是 | 目标仓库/目录的绝对路径 |
| `model` | 否 | Grok模型ID，预先验证。默认值：`grok-4.5` |
| `permission_mode` | 否 | 请参见下面的[权限](#无头权限-验证行为) |
| `session_id` | 否 | 先前结果的会话UUID - 在会话上下文完整的情况下恢复该会话 |
| `background` | 否 | `true` → 立即返回并带有`job_id`；轮询`grok_task_result` |
| `timeout_ms` | 否 | 任务超时（默认15分钟，限制10秒 - 2小时） |
| `effort` | 否 | `low` / `medium` / `high`（映射到grok的`--effort`）。默认值：`high` |
运行 `grok --no-auto-update -p "<prompt>" -m <model> -s <uuid> --output-format json`（` -r <uuid>` 在恢复时）并将进程`cwd`设置为目标仓库和完整用户环境，以便grok使用缓存的`~/.grok`中的现有OAuth登录（不需要`XAI_API_KEY`）。
**对于任何非琐碎的任务，请传递`background: true`。** MCP客户端超时长同步请求（通常约60秒）；超时请求看起来像错误，而任务继续运行并编辑文件。后台模式完全避免了这种情况。如果同步调用在运行过程中被取消，作业仍继续运行，响应会告知您`job_id`以便稍后获取 - 而同步运行会发送MCP进度通知，这使得支持它们的客户端不会超时。
### `grok_task_result`
获取作业的结果：`job_id`（必需），`max_wait_ms`（默认25秒，最大50秒每次调用 - 请重复调用，直到它报告`running`）。
### `grok_task_status`
非阻塞状态。传递`job_id`用于一个作业，不传递则列出所有已知作业。
### `grok_task_cancel`
终止队列中或正在运行的作业（`SIGTERM`，然后`SIGKILL`）。返回作业留下的git验证的部分更改。已完成的作业不受影响。
**作业记录保留到`~/.grok-mcp/jobs/`** （最近100个），因此`grok_task_result`在服务器重启后仍然有效 - 包括Claude Desktop重启，这是服务器升级所需的。如果作业在服务器崩溃时正在运行，则会报告为失败，停止原因`ServerRestart`，并提供通过git验证或恢复会话的说明；其结果未被捕获。
**并发性：同一个`cwd`中的作业** 严格按顺序运行。`files_changed`的git快照差异使`files_changed`值得信赖，假设每个工作树有一个写入者，并且在一个仓库中并行运行grok会导致冲突。调度到同一个目录的第二个作业会被排队（调度响应会告知您，并附上作业）；不同的目录可以自由并行运行。
### `grok_models`
列出grok本地模型缓存中的有效模型ID。`grok_task`还会预先验证模型，并在错误消息中提供有效的ID，并为近似匹配建议“您是否意味着”。
## 结果负载
每个结果都包含人类可读的文本和`structuredContent`：
```json
{
"v": 2,
"success": true,
"stop_reason": "EndTurn",
"job_id": "6c8a1268-…",
"session_id": "068253b9-…",
"files_changed": ["a.txt", "b.txt", "c.txt"],
"files_changed_source": "git",
"diff_stat": " 2 files changed, 2 insertions(+), 2 deletions(-)",
"commands_run": ["npm test"],
"duration_ms": 28699,
"model": "grok-4.5",
"context_tokens_used": 21871,
"tool_calls_count": 4,
"final_response": "…grok's own summary…",
"response_truncated": false,
"warnings": []
}
```
`v`是负载模式版本 - 如果您依赖于该模式，请在解析前检查它。`final_response`限制为16,000个字符（当截断时`response_truncated: true`）。`context_tokens_used` / `tool_calls_count`来自grok的会话信号，这是尽力而为的 - 用于调度许多作业时的预算。
- **`files_changed` 是事实依据，而不是叙述**：服务器在运行前后快照`git status --porcelain -uall`，并对两者进行差异比较（以及跨作业提交的`git diff --name-only`）。运行前脏树是可以的 - 只列出新更改。`diff_stat`仅限于这些文件。在非git目录中，它会退回到解析grok的会话记录并通过`files_changed_source: "transcript"`进行说明。
- 一个刻意的盲点：`git status --porcelain -uall` 看不到 **gitignored** 文件的编辑（`.env.local`、构建输出等）。如果作业仅触及忽略的文件，则`files_changed` 为空 - 按照设计，但值得了解。
- **`success: false` 意味着它**：任何运行以grok的 `stopReason` 除`EndTurn` 之外的作业（`Cancelled` 或 grok以后添加的任何内容）返回 `isError: true` - 即使 grok 在这些情况下退出状态码为 0。路径上列出的更改明确标记为 **部分工作**：作业在 grok 认为任务完成之前停止，可以在编辑后保留。
## 先决条件
- [Grok Build](https://grok.com) CLI 已安装（`grok` 二进制文件，默认位置 `~/.grok/bin/grok`）
- 通过 OAuth 登录：运行 `grok login` 一次在终端
- Node.js 18+
## 安装和构建
```bash
git clone https://github.com/maikunari/grok-mcp.git
cd grok-mcp
npm install
npm run build
```
## 在Claude Desktop中注册
将以下内容添加到您的Claude Desktop配置中（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`），合并到现有的`mcpServers`块中，如果您已经有一个，然后完全退出并重新打开Claude Desktop：
```json
{
"mcpServers": {
"grok": {
"command": "node",
"args": ["/absolute/path/to/grok-mcp/dist/index.js"]
}
}
}
```
> **提示：** Claude Desktop使用最小的`PATH`启动MCP服务器。如果您的`node`来自nvm、Homebrew或其他版本管理器，请使用`node`二进制文件的绝对路径（使用`which node`查找）作为`command`值。
## 在Claude Code中注册
```bash
claude mcp add --scope user grok -- node /absolute/path/to/grok-mcp/dist/index.js
```
（`--scope user`使其在每个项目中都可用；省略它以仅为当前项目注册。 在新会话中生效。）
## 配置
可选环境变量（在服务器条目中添加一个`"env": { ... }`对象）：
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `GROK_TASK_TIMEOUT_MS` | `900000` （15分钟） | 默认每任务超时（`timeout_ms`覆盖每个调用） |
| `GROK_BIN` | `~/.grok/bin/grok` （回退到`PATH`上的`grok`） | grok二进制文件路径 |
## 无头权限（验证行为）
无头grok没有TTY来回答批准提示。 在Grok Build 0.2.87上验证：当工具需要无法授予的批准时，grok **取消运行** - 退出代码0，`stopReason: "Cancelled"`，没有更改被保留。 该服务器将此报告为失败，而不是结果。
编码任务的模式速查表：
| `permission_mode` | 无头行为 |
| --- | --- |
| `auto` | **推荐首选。** 编辑 + shell命令完成（此处在grok 0.2.87–0.2.93、git和非git目录、同步和后台验证）。 *但是*：存在`auto`在其他机器上取消第一次写入的现场报告 - 可能依赖于grok版本或工作区信任。如果您的运行在`auto`下取消，请升级到`bypassPermissions` |
| `bypassPermissions` | 所有内容都自动批准 - 唯一抑制每个门的模式。 无人值守编码的可靠模式，但代价是信任扩展：grok批准其在该cwd中的所有命令和写入 |
| `acceptEdits` | **不支持无头** - 在第一次文件写入、创建 *或* 编辑时取消，甚至没有shell命令（验证）。 尽管名称如此，但它似乎需要交互式UI |
| `default` / 省略 | 使用用户的全局配置；如果有未经批准的工具，则取消 |
显式`permission_mode` **覆盖** 用户的全局始终批准配置 - 传递`acceptEdits`会使运行失败，即使省略它会成功。
替代每个调用的模式： 在`~/.grok/config.toml`中启用全局自动批准（适用于**所有** grok会话，包括交互式会话）：
```toml
[ui]
permission_mode = "always-approve"
```
注意：项目作用域的`<repo>/.grok/config.toml` **不能** 携带权限设置 - grok仅从项目配置中读取`[mcp_servers]`（针对0.2.87文档验证）。 服务器从不创建或修改任何配置文件；如果未检测到自动批准，则结果中包含警告。
## 认证
使用现有的Grok Build OAuth登录（令牌缓存在`~/.grok/auth.json`中）。 如果任务因身份验证过期消息而失败，请在终端中运行`grok login`并重试。
## 开发
`npm run test:cli` 固定了此服务器依赖的grok CLI行为（3个短的真实grok调用）：`-s`创建新会话，现有会话出现`already in use`错误，`-r`恢复上下文。 Grok自己的README声称`-s`恢复 - 其`--help`是正确的，本服务器遵循它。 如果grok更改`-s`为恢复，此测试将大声失败，而不是服务器静默中断。
## 许可证
MIT
