mcp-grok-executor

An MCP server that turns Grok CLI into the execution agent for Claude Code.

Claude plans, reviews, and verifies. Grok implements, runs tests, and fixes failures. This server is the bridge: it exposes Grok's headless CLI as a set of MCP tools — including a fully orchestrated execute → verify → auto-fix loop — so the advisor model never has to babysit the executor.

You ──► Claude Code  (advisor: plan / review / judge evidence)
              │
              │  MCP (stdio)
              ▼
      mcp-grok-executor
              │  grok -p … --always-approve   (subscription OAuth)
              ▼
         Grok CLI  (executor: edit files / run tests / fix)
              │
              ▼
       your project (cwd)

Why

Pairing two models works best with a clear division of labor: a strong reasoning model that owns the design and the acceptance criteria, and a fast execution model that grinds through implementation. Doing that by hand means endless copy-paste. This server makes the loop native to Claude Code:

1. You approve a plan.
2. Claude calls run_task with a prompt and a verify_command (e.g. npm test).
3. The server runs Grok, collects git status + diff, runs your verify command, and — if it fails — automatically sends the failure output back to the same Grok session, up to max_fix_attempts times.
4. Claude receives a single structured result: every attempt, the diff, the changed files, the verify output. It judges the evidence instead of orchestrating the steps.

Requirements

• Node.js ≥ 20

• Grok CLI on your PATH, logged in via subscription OAuth:

  grok login
  grok --no-auto-update -p "Say ok."   # sanity check
  

  No XAI_API_KEY needed — auth comes from ~/.grok/auth.json.

• Claude Code (or any MCP client that speaks stdio).

Install

git clone https://github.com/emigrete/mcp-grok-executor.git
cd mcp-grok-executor
npm install
npm run build

Connect to Claude Code

Globally (recommended) — available in every project:

claude mcp add --scope user grok -- node /absolute/path/to/mcp-grok-executor/dist/index.js

Per project — drop a .mcp.json in the project root:

{
  "mcpServers": {
    "grok": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-grok-executor/dist/index.js"]
    }
  }
}

If the grok binary is not on the PATH Claude Code inherits, add "env": { "GROK_BIN": "/path/to/grok" }.

Tools

Tool	Mutates?	Purpose
auth_status	No	Check Grok login (~/.grok/auth.json)
review_task	No	Read-only analysis: Grok runs with write/shell tools disabled
execute_task	Yes	One-shot implementation run (--always-approve)
run_task	Yes	Orchestrated loop: execute → git evidence → verify → auto-fix
continue_task	Optional	Follow-up prompt into a previous Grok session
task_status	No	Poll background jobs, read the live activity log. Job records survive server restarts and are also exposed as MCP resources (grok://jobs/recent, grok://jobs/{id})
cancel_task	No	Cancel a running background job (kills the whole process tree)

Common arguments

Every Grok-running tool takes:

• prompt (string, required) — self-contained task brief for Grok
• cwd (string, required) — absolute path to the target project
• model, max_turns, timeout_sec (optional) — per-run overrides
• background (optional bool) — return a job_id immediately; poll with task_status

run_task — the orchestrated loop

run_task({
  prompt:             "Fix the failing suite. Don't touch the tests.",
  cwd:                "/abs/path/to/project",
  verify_command:     "npm test",        // omitted → git evidence only
  max_fix_attempts:   2,                 // default 2; 0 disables auto-fix
  verify_timeout_sec: 300                // default 300
})

Returns structured evidence:

{
  "ok": true,
  "status": "completed",
  "sessionId": "…",
  "totalTokens": 12345,
  "attempts": [
    {
      "type": "execute",
      "exitCode": 0,
      "summary": "…",
      "durationMs": 12314,
      "usage": { "numTurns": 3, "totalTokens": 4200 }
    }
  ],
  "git": {
    "isRepo": true,
    "changedFiles": ["src/foo.js"],
    "statusAfter": " M src/foo.js\n",
    "diff": "diff --git a/src/foo.js …",
    "noChanges": false
  },
  "verify": { "command": "npm test", "ran": true, "exitCode": 0, "output": "…", "attemptsUsed": 1 }
}

status is one of completed | failed | needs_advisor:

• completed — Grok succeeded and verify passed (or no verify was requested).
• failed — Grok or verify failed after retries were exhausted.
• needs_advisor — the executor hit a genuinely ambiguous or destructive decision. Nothing is changed; the result includes a question for the advisor. Answer via continue_task with the returned session_id (and your decision in the prompt).

totalTokens (and per-attempt usage) surface cost so the advisor can see how expensive the loop was.

Loop policy:

• Auto-retry triggers only on verify_command failure. Each retry continues the same Grok session with the failure output and a fixed instruction to fix the underlying issue (never to weaken or delete tests).
• A failed Grok run aborts immediately — there is no verification signal to feed back.
• An empty diff never consumes retries; it is reported as git.noChanges: true for the advisor to judge (it may be legitimate).
• A verify timeout counts as a failure and enters the fix loop.
• ok is true only when Grok succeeded and the final verify passed (or none was requested).

Watching Grok work live

The server runs Grok with --output-format streaming-json and parses the stream as it arrives. Two layers of visibility:

1. MCP progress notifications — during any synchronous call, Grok's narration ([thought] …, [grok] …) streams into the client's progress UI. In Claude Code you watch it think and act in the tool spinner.

2. Live job log — every event is appended to the job log in real time. For background jobs, task_status returns the growing feed, or just:

   tail -f ~/.cache/mcp-grok-executor/jobs/<job_id>.log
   

ACP transport — set MCP_GROK_TRANSPORT=acp to run execute_task / run_task (and fix retries) over grok agent stdio instead of the CLI stream. Visibility upgrades from narration to real tool events: [tool] run_terminal_command — npm test, per-file writes with paths, and status updates as tools complete. review_task, background jobs, and continue_task / recent-session resume still use the CLI transport.

Sessions

execute_task and run_task return a sessionId. Pass it to continue_task for stateful follow-ups ("now update the changelog", "fix the two remaining test failures") — Grok resumes with full context of what it just did.

Configuration

Variable	Default	Meaning
GROK_BIN	grok	Path to the Grok CLI
GROK_AUTH_PATH	~/.grok/auth.json	Auth file checked by auth_status
MCP_GROK_TIMEOUT_SEC	600	Default timeout per Grok run
MCP_GROK_MAX_OUTPUT_CHARS	80000	Truncation budget for inline output
MCP_GROK_MODEL	(CLI default)	Default -m passed to Grok
MCP_GROK_CACHE_DIR	~/.cache/mcp-grok-executor	Job records + logs
MCP_GROK_TRANSPORT	cli	cli (default) or acp (experimental — real tool events via grok agent stdio)
MCP_GROK_REVIEW_TOOLS	read-only set	Tool allowlist for review_task
MCP_GROK_REVIEW_DISALLOWED	write/shell set	Tools stripped in review_task

Advisor policy

CLAUDE.md ships the advisor/executor policy for Claude Code: plan first, delegate after approval, prefer run_task with a verify_command, always judge the returned evidence. Copy it (or merge it into your own CLAUDE.md) in projects where you want the full workflow, and optionally install agents/fable-advisor.md into ~/.claude/agents/.

Development

npm run typecheck   # tsc --noEmit (includes tests)
npm test            # unit tests (node:test + tsx)
npm run build       # compile to dist/ (tests excluded)
npm run smoke       # build + tests + real grok hello + MCP round-trip

The test suite covers the stream parser, the runner (against a fake grok binary), git evidence, the shell runner, the orchestrator loop policy, and progress-notification throttling.

Security notes

• execute_task and run_task run Grok with --always-approve — treat them like giving an autonomous agent full access to cwd. Gate them behind manual approval in your MCP client; leave review_task/auth_status unrestricted.
• Concurrent run_task calls on the same cwd are rejected by a per-cwd lock (avoids two agents fighting over the same tree).
• cancel_task kills the whole process tree of the background job, not just the top-level process.
• verify_command is arbitrary shell executed in cwd — same trust level as the execution tools. Only pass commands you'd run yourself.
• review_task disables Grok's write and shell tools and injects a read-only constraint, but it still runs a model with read access. Spot-check git status if in doubt.
• Never add --debug / --debug-file to the Grok invocation: the Grok debug log prints the OAuth bearer token in plaintext.
• Job logs under ~/.cache/mcp-grok-executor contain prompts and outputs — don't put secrets in prompts.

Roadmap

• ACP for review_task via restricted profiles (tool visibility without write/shell).
• Interactive needs_advisor over MCP elicitation (in-band Q&A instead of return-and-continue_task).
• Session/load-based continue_task over ACP (resume the same agent session without falling back to CLI).

License

MIT