grok-build-mcp-server

An MCP stdio server that exposes the Grok Build 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 for what shipped and 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 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

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:

{
  "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 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:

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:

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 refused tool is not mistaken for a model that gave up. The server can see which call failed, not why the CLI refused it. 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:

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

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

Tools

Read the full README on GitHub →