Skip to main content
Glama
maikunari

grok-mcp

by maikunari
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

grok-mcp

A minimal local MCP server (stdio) that lets Claude Desktop or Claude Code delegate coding tasks to Grok Build running headless as a subagent.

Built for supervising agents: results are ground-truthed against git (no phantom "files modified"), failures are honest failures, long tasks run as background jobs, and every result carries a machine-readable structuredContent payload.

Tools

grok_task

Input

Required

Description

prompt

yes

The coding task for Grok Build

cwd

yes

Absolute path to the target repo/directory

model

no

Grok model ID, validated up front. Default: grok-4.5

permission_mode

no

See permissions below

session_id

no

Session UUID from a previous result — resumes that session with context intact

background

no

true → return immediately with a job_id; poll grok_task_result

timeout_ms

no

Per-task timeout (default 15 min, clamped 10 s – 2 h)

effort

no

low / medium / high (maps to grok's --effort). Default: high

Runs grok --no-auto-update -p "<prompt>" -m <model> -s <uuid> --output-format json (-r <uuid> when resuming) with the process cwd set to your target repo and your full user environment, so grok uses your existing OAuth login cached in ~/.grok (no XAI_API_KEY needed or used).

For anything non-trivial, pass background: true. MCP clients time out long synchronous requests (typically ~60 s); a timed-out request looks like an error while the task keeps running and editing files. Background mode sidesteps that entirely. If a synchronous call does get cancelled mid-run, the job keeps running and the response tells you the job_id to fetch later — and synchronous runs send MCP progress notifications, which keeps clients that support them from timing out at all.

grok_task_result

Fetch the outcome of a job: job_id (required), max_wait_ms (default 25 s, max 50 s per call — call repeatedly while it reports running).

grok_task_status

Non-blocking status. Pass job_id for one job, omit to list all known jobs.

grok_task_cancel

Kill a queued or running job (SIGTERM, then SIGKILL). Returns the git-verified partial changes the run left on disk. Finished jobs are unaffected.

Job records persist to ~/.grok-mcp/jobs/ (last 100), so grok_task_result still works after a server restart — including the Claude Desktop restart that a server upgrade requires. A job that was mid-run when the server died is reported as failed with stop reason ServerRestart and instructions to verify via git or resume the session; its outcome was not captured.

Concurrency: jobs in the same cwd run strictly serially. The git snapshot-diff that makes files_changed trustworthy assumes one writer per working tree, and parallel grok runs in one repo would conflict anyway. A second job dispatched into the same directory is queued (the dispatch response says so, and behind which job); different directories run in parallel freely.

grok_models

Lists valid model IDs from grok's local model cache. grok_task also validates the model up front and puts the valid IDs in the error message, with a "did you mean" suggestion for near-misses (composer-2.5 → grok-composer-2.5-fast).

Related MCP server: Clanker

Result payload

Every result includes human-readable text plus structuredContent:

{
  "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_call_count": 4,
  "final_response": "…grok's own summary…",
  "response_truncated": false,
  "warnings": []
}

v is the payload schema version — check it before parsing if you depend on the shape. final_response is capped at 16 000 chars (response_truncated: true when cut). context_tokens_used / tool_call_count come from grok's session signals, best effort — for budgeting when dispatching many jobs.

  • files_changed is ground truth, not narration: the server snapshots git status --porcelain -uall before and after the run and diffs the two (plus git diff --name-only across any commits the task made). A dirty tree before the run is fine — only new changes are listed. diff_stat is scoped to those files. In non-git directories it falls back to parsing grok's session transcript and says so via files_changed_source: "transcript".

  • One deliberate blind spot: git status --porcelain -uall doesn't see edits to gitignored files (.env.local, build output, …). If a task only touches ignored files, files_changed is empty — by design, but worth knowing.

  • success: false means it: any run ending with grok's stopReason other than EndTurn (Cancelled, or anything grok adds later) returns isError: true — even though grok exits 0 in those cases. Changes listed on that path are explicitly labeled partial work: the run stopped before grok considered the task done, and a cancel can land after some edits persisted.

  • commands_run is best-effort transcript parsing (grok's headless output has no tool-call events), scoped to the current turn for resumed sessions.

Prerequisites

  • Grok Build CLI installed (grok binary, default location ~/.grok/bin/grok)

  • Logged in via OAuth: run grok login once in a terminal

  • Node.js 18+

Install & build

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

Register in Claude Desktop

Add this to your Claude Desktop config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), merging into an existing mcpServers block if you have one, then fully quit and reopen Claude Desktop:

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

Tip: Claude Desktop launches MCP servers with a minimal PATH. If your node comes from nvm, Homebrew, or another version manager, use the absolute path to the node binary (find it with which node) as the command value instead of "node".

Register in Claude Code

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

(--scope user makes it available in every project; omit it to register for the current project only. Takes effect in new sessions.)

Configuration

Optional environment variables (add an "env": { ... } object to the server entry):

Variable

Default

Purpose

GROK_TASK_TIMEOUT_MS

900000 (15 min)

Default per-task timeout (timeout_ms overrides per call)

GROK_BIN

~/.grok/bin/grok (falls back to grok on PATH)

Path to the grok binary

Headless permissions (verified behavior)

Headless grok has no TTY to answer approval prompts. Verified on Grok Build 0.2.87: when a tool needs an approval nothing can grant, grok cancels the run — exit code 0, stopReason: "Cancelled", no changes persisted. This server reports that as a failure, never as a result.

Mode cheat-sheet for coding tasks:

permission_mode

Headless behavior

auto

Recommended first choice. Edits + shell commands complete (verified here on grok 0.2.87–0.2.93, git and non-git dirs, sync and background). However: field reports exist of auto cancelling at the first write on other machines — likely grok-version or workspace-trust dependent. If your runs cancel under auto, escalate to bypassPermissions

bypassPermissions

Everything auto-approved — the only mode that suppresses every gate. The reliable mode for unattended coding, at the cost of a real trust expansion: grok approves all its own commands and writes in that cwd

acceptEdits

Not headless-viable — cancels at the first file write, creation or edit, even with no shell commands (verified). Despite the name, it appears to require an interactive UI

default / omitted

Uses the user's global config; cancels on any unapproved tool

An explicit permission_mode overrides the user's global always-approve config — passing acceptEdits makes runs fail even on machines where omitting it would work.

Alternative to per-call modes: enable global auto-approve in ~/.grok/config.toml (applies to all grok sessions, including interactive ones):

[ui]
permission_mode = "always-approve"

Note: a project-scoped <repo>/.grok/config.toml cannot carry permission settings — grok only reads [mcp_servers] from project config (verified against 0.2.87 docs). The server never creates or modifies any config file; if no auto-approval is detected, the result includes a warning instead.

Auth

Uses your existing Grok Build OAuth login (token cached in ~/.grok/auth.json). If a task fails with the auth-expired message, run grok login in a terminal and retry.

Development

npm run test:cli pins the grok CLI behavior this server depends on (3 short real grok calls): -s creates new sessions and errors already in use on existing ones, -r resumes with context. Grok's own README claims -s resumes — its --help is correct and this server follows it. If grok ever changes -s to resume, this test fails loudly instead of the server breaking quietly.

License

MIT

Available Tools

5 tools
grok_modelsA

List available Grok model IDs (from grok's local model cache).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It adds behavioral context (reads from local cache) but does not disclose return format, potential side effects, or performance implications. For a simple list tool, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the verb and resource, providing all necessary information without any waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is largely complete. However, it does not specify the return format (e.g., array of strings) or behavior when the cache is empty, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the schema documentation coverage is 100%. The description does not need to add parameter info. A score of 4 is baseline for zero-parameter tools, as the description adds no parameter semantics but is not deficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'available Grok model IDs', with additional context about the source ('from grok's local model cache'). This distinguishes it from sibling tools which focus on tasks (grok_task, grok_task_cancel, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining model IDs but does not explicitly state when to use this tool versus alternatives. Since sibling tools handle tasks, context suggests using this before task creation, but no direct guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_taskA

Delegate a coding task to Grok Build (headless) as a subagent. Runs in the given repository using the user's existing Grok OAuth login. Returns grok's response plus a git-verified list of files changed and commands run. For tasks likely to exceed ~1 minute, pass background: true and poll grok_task_result — long synchronous calls can hit the MCP client's request timeout. Jobs in the same cwd run serially (queued) to keep results accurate. To continue a previous task with context intact, pass its session_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdYesAbsolute path to the target repository/directory the task should run in.
modelNoGrok model ID (default: grok-4.5). Use grok_models to list valid IDs. Pass grok-composer-2.5-fast for Composer.
effortNoGrok effort level (maps to --effort; default: high).
promptYesThe coding task for Grok Build to perform.
backgroundNoIf true, return immediately with a job_id; fetch the outcome with grok_task_result. Recommended for anything non-trivial.
session_idNoSession UUID from a previous grok_task result. Resumes that session so grok keeps its context (files read, decisions made) instead of starting cold.
timeout_msNoPer-task timeout in ms (default 900000, clamped to 10s–2h).
permission_modeNoGrok permission mode. Headless-viable for coding tasks: "auto" (recommended) or "bypassPermissions". "acceptEdits" is NOT headless-viable — it cancels the run at the first file write. Omit to use grok's default (relies on the user's global config).

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool runs headlessly using the user's OAuth, returns a list of files changed and commands run (implying modifications), and that background tasks return immediately. It also mentions serial queuing and timeout behavior. It lacks details on error handling or destructive potential, but the implied file changes are sufficient for an agent to infer mutability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph of 5 sentences, all carrying essential information. It front-loads the main purpose and key usage notes. While it could be slightly more structured with bullet points, it has no wasted words and is easy to scan. The conciseness is good for a tool with complex behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters (2 required), no output schema, and no annotations, the description covers critical aspects: when to use background, session continuation, serial queuing, permission mode restrictions, and timeout range. It does not describe the exact return format beyond 'response plus git-verified list of files changed and commands run', which may require the agent to infer structure. Overall, it provides sufficient context for an unfamiliar agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all 8 parameters have descriptions), so baseline is 3. The description adds significant value: it explains that background avoids timeouts and requires polling grok_task_result, that session_id carries context, that permission_mode has headless-viable options (auto, bypassPermissions) and warns against acceptEdits, and that timeout_ms has a default with clamp. This goes well beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Delegate a coding task to Grok Build (headless) as a subagent.' It specifies the verb (delegate), resource (Grok Build), and context (headless subagent in a repository). It also mentions what it returns (response plus git-verified list), distinguishing it from siblings like grok_task_result which is for polling background tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use background mode ('tasks likely to exceed ~1 minute') and warns against long synchronous calls ('can hit the MCP client's request timeout'). It also suggests using session_id to continue a previous task and notes that jobs in the same cwd run serially. However, it does not explicitly state when not to use this tool or compare it directly to all siblings (e.g., grok_task_cancel, grok_task_status).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_cancelA

Cancel a queued or running grok_task job. Kills the grok process and returns the verified partial changes on disk. Finished jobs are not affected.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesJob ID to cancel.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses that it 'kills the grok process' and 'returns verified partial changes on disk', providing good behavioral insight beyond the basic cancel action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. Front-loaded with action and immediately explains scope and effect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers when to use, what happens, and what is returned. Lacks mention of authorization or rate limits, but for a simple cancellation tool with one param, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%. The description adds context that job_id refers to a grok_task job and explains the effect of cancellation, offering more than the schema's minimal 'Job ID to cancel'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Cancel' and the resource 'grok_task job'. It distinguishes from siblings by specifying applicability to queued or running jobs, not finished ones.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: cancel only queued or running jobs, not finished ones. It does not explicitly mention alternative tools like grok_task_status for checking status, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_resultA

Fetch the result of a grok_task job (background, or one whose request timed out). Waits up to max_wait_ms for completion, then returns either the final result or a still-running status. Safe to call repeatedly. Results persist across server restarts.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesJob ID returned by grok_task.
max_wait_msNoHow long to wait for completion before returning (default 25000, max 50000).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses waiting behavior (max_wait_ms), returns final result or still-running status, safe to call repeatedly, and persistence across restarts. Could mention potential errors or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with purpose. No redundant information, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, behavior, persistence, and repeatability. Lacks description of return format or error states, but for a simple 2-param tool with no output schema, it is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds value by specifying default and max for max_wait_ms (25000, 50000) and clarifying job_id is from grok_task, enhancing schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Fetch the result of a grok_task job', specifying verb and resource. Distinguishes from sibling tools like grok_task (start), grok_task_status (status), grok_task_cancel (cancel) by focusing on result retrieval for background/timeout jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: use after grok_task completes or times out. Explains safe to call repeatedly and persists across restarts. Lacks explicit when-not-to-use, but sibling differentiation implies alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_statusA

Check status of grok_task jobs without blocking. Pass job_id for one job, omit it to list all known jobs (including persisted ones from previous server sessions).

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idNoOptional job ID to check.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses non-blocking behavior and that listing includes persisted jobs from previous sessions. No contradictions. Could add more detail about response format or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with key purpose, no extraneous words. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is fully complete. It covers both modes and the behavior across server sessions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter job_id is described in schema as optional. The description adds value by clarifying that omitting it lists all jobs, while providing it checks a specific job. This enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks status of grok_task jobs, with two distinct modes (single job by job_id, or list all jobs). It effectively distinguishes from sibling tools like grok_task (creation), grok_task_cancel, and grok_task_result.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: pass job_id for one job, omit to list all. It implies the tool is for non-blocking status checks without blocking. However, it does not explicitly contrast with siblings or state when not to use, though context signals make alternatives clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.4.0
    • First observedgrok_models
    • First observedgrok_task
    • First observedgrok_task_cancel
    • First observedgrok_task_result
    • First observedgrok_task_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: listing models, starting a task, canceling, fetching results, and checking status. There is no functional overlap.

Naming Consistency5/5

All tools follow a consistent 'grok_' prefix with snake_case, and the suffixes clearly indicate the operation (models, task, task_cancel, task_result, task_status).

Tool Count5/5

5 tools cover the essential operations for the subagent-based task system: initiate, cancel, poll results, check status, and list models. No tools are missing or extraneous.

Completeness5/5

The set provides complete lifecycle coverage for tasks (create, monitor, cancel, retrieve results) plus model listing. All common agent workflows are supported without obvious gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • code-bridge

    ITSWProj
    A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that bridges Claude Desktop with Claude Code, allowing users to delegate tasks to Claude Code directly from Claude Desktop conversations, supporting both synchronous and background execution with session reuse.
    5
    MIT

  • claude-bridge-mcp

    millanrp25-dot
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that lets ChatGPT or any MCP client securely delegate coding tasks to a local Claude Code instance, with git checkpointing, approval gates, and structured results. Supports code review, test running, and rollback via simple tool calls.
    16
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maikunari/grok-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server