grok-build-to-claude

# grok-build-mcp-server

[![npm](https://img.shields.io/npm/v/grok-build-mcp-server?style=flat-square)](https://www.npmjs.com/package/grok-build-mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.Nuruvala%2Fgrok--build--mcp--server-6E56CF?style=flat-square)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Nuruvala/grok-build-mcp-server)
[![CI](https://img.shields.io/github/actions/workflow/status/Nuruvala/grok-build-to-claude/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Nuruvala/grok-build-to-claude/actions/workflows/ci.yml)
[![Node](https://img.shields.io/node/v/grok-build-mcp-server?style=flat-square)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=grok-build&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22grok-build-mcp-server%22%5D%7D)
[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_server-1c1c1c?style=flat-square)](https://cursor.com/install-mcp?name=grok-build&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdyb2stYnVpbGQtbWNwLXNlcnZlciJdfQ%3D%3D)

An [MCP](https://modelcontextprotocol.io) stdio server that exposes the [Grok Build](https://x.ai)
CLI (`grok`) as tools you can call from Claude Code, Cursor, VS Code, or any other MCP client.

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

It is a thin process wrapper. It does not reimplement agent logic and does not talk to the xAI API
directly — all the intelligence stays in the `grok` CLI. What this server adds is faithful argument
construction, robust process supervision, and clean MCP-shaped output.

> **Status: 0.2.2.** The tool surface is complete. The server runs real headless Grok agents in the
> foreground or detached in the background, streams progress while they run, stops a run on request,
> reviews git diffs, researches questions on the web, lists the sessions those runs created, and
> reports session, usage, and cost. See [CHANGELOG.md](CHANGELOG.md) for what shipped and
> [ROADMAP.md](ROADMAP.md) for what was considered and rejected.

## Progress

A long agent run is visible while it happens, rather than a silent wait ending in a wall of text.
When your client sends a `progressToken`, the server runs Grok with `--output-format streaming-json`
and forwards a notification per event:

```
#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)
```

Progress tracks what the agent is doing, not what phase it is in. Reasoning and response text are
coalesced so a token stream does not flood your client, while tool calls are reported as they
happen. Clients that support `resetTimeoutOnProgress` will not time out mid-run.

A client that sends no `progressToken` gets the cheaper non-streaming path and pays nothing for
this.

## Requirements

- [Grok Build CLI](https://x.ai) 1.0.0 or newer, authenticated (`grok models` should succeed)
- Node.js 22 or newer

If `grok` is not on your `PATH`, set `GROK_BINARY` to its full path when you register the server.

## Install

### Claude Code

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

`-s user` registers the server for your whole account rather than for the directory you happen to be
in. Without it the scope is that one project, which is rarely what you want for a general coding
assistant, and the symptom is a server that is missing the next time you start Claude Code somewhere
else.

Then, in Claude Code:

```
> use the grok-build check tool
```

`check` reports the resolved binary, the CLI version, whether you are authenticated, and the active
permission ceiling. If it is happy, the rest will work.

### Any other MCP client

The server speaks MCP over stdio and takes no arguments of its own:

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

VS Code and Cursor accept the install badges at the top of this page, which carry exactly that
configuration.

Clients that install from the [MCP Registry](https://registry.modelcontextprotocol.io) know this
server as `io.github.Nuruvala/grok-build-mcp-server`. The registry entry is published from the same
tag as the npm release and points at the same package.

### If `npx` cannot find the server

`npx` resolves a bare package name against the _local_ project first. If your MCP client's working
directory is a checkout of this repository — or of anything else whose `package.json` is named
`grok-build-mcp-server` — `npx -y grok-build-mcp-server` runs the local entry point, does not find
one, and fails with `command not found`. Install it somewhere of its own and register that path:

```bash
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
```

## Permissions

Grok runs launched through this server are **read-only by default**: `--permission-mode plan` with
`--sandbox read-only`. Nothing can modify your files until you say so.

Permission is a **ceiling**, set once when you register the server, rather than a prompt on every
call. Three levels:

| Level                 | `--permission-mode` | `--sandbox` | What it allows                     |
| --------------------- | ------------------- | ----------- | ---------------------------------- |
| `read-only` (default) | `plan`              | `read-only` | Reading and reasoning. No edits    |
| `write`               | `auto`              | `workspace` | Edits inside the working directory |
| `full`                | `bypassPermissions` | `off`       | Unattended full approval           |

The sandbox is not advisory, and a refusal is not a warning. Under `write` the run **cannot write
outside `cwd`**, and a refused tool call ends the **whole run**: the CLI reports
`stopReason: cancelled`, exits 0, and returns only whatever the model had said before the refusal.
The server names the refused call and its path in that case, so a sandbox refusal is not mistaken
for a model that gave up. If a run must write somewhere else, say a report outside the repository,
either point it at a path inside `cwd` or use `full`.

`write` uses `--permission-mode auto` rather than `acceptEdits`, which is measured rather than
inherited from the flag's name. Headless grok has no human to accept an edit, so under
`acceptEdits`, `dontAsk` and `default` every file mutation is refused and the run dies, on both
sandbox profiles. `auto` and `bypassPermissions` both work; `auto` is the narrower one, and it still
refuses a write outside the workspace, so `full` remains a real step up rather than a synonym.

To let Grok make edits:

```bash
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
```

Use `full` only if you already run your MCP client with full approval and want the delegated Grok
run to be equally unattended. It grants the spawned `grok` process the same authority you have.

A call that requests more than the ceiling is **rejected, not silently downgraded** — a clamped run
would report success while changing nothing, which is worse than a clear error.

## Environment variables

| Variable                       | Default                    | Purpose                                                          |
| ------------------------------ | -------------------------- | ---------------------------------------------------------------- |
| `GROK_BINARY`                  | `grok`                     | Path to the `grok` executable                                    |
| `GROK_MCP_PERMISSION_CEILING`  | `read-only`                | Highest level any call may request                               |
| `GROK_MCP_DEFAULT_PERMISSION`  | `read-only`                | Level used when a call requests none                             |
| `GROK_MCP_DEFAULT_MODEL`       | `grok-4.6`                 | Model when a call omits one. `none` defers to the CLI            |
| `GROK_MCP_DEFAULT_EFFORT`      | `high`                     | Reasoning effort when a call omits one. `none` defers to the CLI |
| `GROK_MCP_TIMEOUT_MS`          | `1800000`                  | Wall clock for a single run                                      |
| `GROK_MCP_STATE_DIR`           | `$XDG_STATE_HOME/grok-mcp` | Background job records                                           |
| `GROK_MCP_MAX_CONCURRENT_RUNS` | `4`                        | Background runs alive at once. `off` for no cap                  |
| `GROK_MCP_LOG_LEVEL`           | `info`                     | `debug`, `info`, `warn`, `error`. Logs go to stderr              |
| `STRUCTURED_CONTENT_ENABLED`   | off                        | Also emit `structuredContent` alongside `_meta`                  |

Grok's own variables (`XAI_API_KEY`, `GROK_HOME`, `GROK_DISABLE_AUTOUPDATER`) pass through to the
child process untouched.

## Tools

| Tool        | Read-only  | Purpose                                                                                         |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `grok`      | by ceiling | Run a headless Grok agent. Prompt, session resume/continue/fork, model, effort, tool allow/deny |
| `review`    | always     | Review a git diff: working tree, a merge-base diff against a ref, or a single commit            |
| `websearch` | always     | Research a question on the web, and report which searches and sources it actually used          |
|