mcp-grok-executor
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-grok-executor Implement the new login API endpoint and run tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
You approve a plan.
Claude calls
run_taskwith a prompt and averify_command(e.g.npm test).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 tomax_fix_attemptstimes.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.
Related MCP server: cc-agent
Requirements
Node.js ≥ 20
Grok CLI on your
PATH, logged in via subscription OAuth:grok login grok --no-auto-update -p "Say ok." # sanity checkNo
XAI_API_KEYneeded — 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 buildConnect to Claude Code
Globally (recommended) — available in every project:
claude mcp add --scope user grok -- node /absolute/path/to/mcp-grok-executor/dist/index.jsPer 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 |
| No | Check Grok login ( |
| No | Read-only analysis: Grok runs with write/shell tools disabled |
| Yes | One-shot implementation run ( |
| Yes | Orchestrated loop: execute → git evidence → verify → auto-fix |
| Optional | Follow-up prompt into a previous Grok session |
| No | Poll background jobs, read the live activity log. Job records survive server restarts and are also exposed as MCP resources ( |
| 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 Grokcwd(string, required) — absolute path to the target projectmodel,max_turns,timeout_sec(optional) — per-run overridesbackground(optional bool) — return ajob_idimmediately; poll withtask_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 aquestionfor the advisor. Answer viacontinue_taskwith the returnedsession_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_commandfailure. 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: truefor the advisor to judge (it may be legitimate).A verify timeout counts as a failure and enters the fix loop.
okis 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:
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.Live job log — every event is appended to the job log in real time. For background jobs,
task_statusreturns 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 |
|
| Path to the Grok CLI |
|
| Auth file checked by |
|
| Default timeout per Grok run |
|
| Truncation budget for inline output |
| (CLI default) | Default |
|
| Job records + logs |
|
|
|
| read-only set | Tool allowlist for |
| write/shell set | Tools stripped in |
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-tripThe 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_taskandrun_taskrun Grok with--always-approve— treat them like giving an autonomous agent full access tocwd. Gate them behind manual approval in your MCP client; leavereview_task/auth_statusunrestricted.Concurrent
run_taskcalls on the samecwdare rejected by a per-cwd lock (avoids two agents fighting over the same tree).cancel_taskkills the whole process tree of the background job, not just the top-level process.verify_commandis arbitrary shell executed incwd— same trust level as the execution tools. Only pass commands you'd run yourself.review_taskdisables Grok's write and shell tools and injects a read-only constraint, but it still runs a model with read access. Spot-checkgit statusif in doubt.Never add
--debug/--debug-fileto the Grok invocation: the Grok debug log prints the OAuth bearer token in plaintext.Job logs under
~/.cache/mcp-grok-executorcontain prompts and outputs — don't put secrets in prompts.
Roadmap
ACP for
review_taskvia restricted profiles (tool visibility without write/shell).Interactive
needs_advisorover MCP elicitation (in-band Q&A instead of return-and-continue_task).Session/load-based
continue_taskover ACP (resume the same agent session without falling back to CLI).
License
Available Tools
7 toolsauth_statusA
Check whether Grok CLI is logged in via ~/.grok/auth.json (subscription OAuth). Call this before first use if unsure.
Inputs: no named parameters.
cancel_taskA
Cancel a running background Grok job by job_id.
Inputs: job_id (required).
continue_taskA
Continue a previous Grok execution session with a follow-up prompt (e.g. fix failing tests). Prefer session_id from a prior execute_task; otherwise continues the most recent session in cwd.
Inputs: cwd (required), prompt (required), model, mutate, +4 more.
execute_taskA
MUTATING: Delegate implementation to Grok (file edits, tests, shell). Uses --always-approve. Only call after the user approved a plan or explicitly asked to implement. Verify with git diff/tests afterwards. Returns session_id for continue_task.
Inputs: cwd (required), prompt (required), model, max_turns, +3 more.
review_taskA
READ-ONLY: Ask Grok to analyze code, review a plan/diff, or answer questions without mutating files. Prefer this before execute_task. Grok runs without --always-approve and with write/shell tools disabled.
Inputs: cwd (required), prompt (required), model, max_turns, +2 more.
run_taskA
ORCHESTRATED + MUTATING: run a full execute → git-evidence → verify → auto-fix loop server-side and return structured evidence (attempts, changed files, diff, verify output). Same approval bar as execute_task: only after the user approved a plan. Prefer this over execute_task when a test/build command can verify the work. If the result has status 'needs_advisor', answer the question via continue_task with the returned session_id. cancel_task also aborts in-flight grok sub-processes.
Inputs: cwd (required), prompt (required), model, max_turns, +6 more.
task_statusA
Poll a background job started with background=true, or list recent jobs if job_id is omitted.
Inputs: job_id, include_log.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools are clearly distinct: auth_status for login, task_status for monitoring, review_task for read-only analysis, execute_task and run_task for mutating work, continue_task for follow-ups, and cancel_task for aborting. The primary ambiguity is between execute_task and run_task, which both delegate implementation to Grok, though the descriptions clarify when to prefer each.
All tools use lowercase_with_underscores and are two-word phrases, but there's a slight inconsistency in suffixes: five tools end in '_task' while two end in '_status'. The pattern is otherwise highly predictable, with verb-led names for actions and noun-led names for status queries, so the deviation is minor.
Seven tools is well-scoped for a Grok executor server. Each tool serves a distinct function in the workflow of delegating tasks, monitoring them, and managing sessions, without feeling bloated or sparse.
The domain of delegating implementation tasks to Grok is well covered: auth check, read-only review, mutating execution (both one-shot and orchestrated), continuation, status polling, and cancellation. A minor gap is the lack of an explicit tool to retrieve full output of a completed job, though task_status may partially address this.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted X Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn MCP server that orchestrates AI coding assistants (Claude Code CLI and Gemini CLI) to perform complex programming tasks autonomously, allowing remote control of your local development environment from anywhere.19 npm140MIT
- AlicenseAqualityDmaintenanceMCP server that spawns autonomous Claude Code agents in GitHub repos, enabling task delegation with persistent state, multi-step workflows, and job monitoring.4776 npm2Apache 2.0
- AlicenseAqualityDmaintenanceAn autonomous MCP server that uses the Claude Code CLI to solve coding problems without permission prompts.1MIT
- AlicenseAqualityFmaintenanceMCP server for running external coding agents as background tasks inside Claude Code. Supports multiple backends including Codex, Grok, GLM, DeepSeek, and more.7MIT