xAI Grok MCP Bridge
Run the local xAI Grok CLI as an MCP sub-agent from Claude Code or any MCP host via WSL2.
Ask Grok: send a new headless prompt/task (
grok_ask) with optional model, workspace, timeout, max turns, reasoning effort, rules, session ID, and raw debug output.Continue sessions: resume a specific Grok session ID or continue the most recent session in a workspace (
grok_continue).Code review: get a strict second-opinion review of code or diffs (
grok_code_review) with optional question, primary analysis, max findings (1–10), self-check, reasoning effort, and raw output.Version check: return the installed Grok CLI version (
grok_version).Parallel calls: run up to 4 concurrent Grok sessions.
Workspace targeting: point Grok at a project directory; defaults to the server’s cwd and converts Windows paths for WSL.
Session control: create new named sessions with UUIDs or resume/continue existing sessions.
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., "@xAI Grok MCP Bridge Review this TypeScript function for potential null pointer errors"
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.
x.ai Grok CLI MCP Bridge
Use the local grok CLI as an MCP sub-agent from Claude Code or any MCP host.
This server wraps the documented x.ai headless scripting mode. The generic tools use JSON output,
while grok_code_review uses plain output because it produced better review results in practice.
grok --no-auto-update --prompt-file /tmp/prompt.md --cwd /path/to/project --output-format jsonRequirements
Windows host with Python 3.10+ and WSL2
Grok installed and authenticated inside the selected Linux distro
Required
GROK_WSL_DISTRO(for exampleUbuntu)Required
GROK_CLI_PATH: absolute Linux executable path inside that distro
The bridge uses WSL only. Native Windows Grok execution and native PATH lookup have been removed. Missing WSL configuration fails before any CLI process is started.
Windows with WSL2
xAI ships grok.exe unsigned. Windows Smart App Control starts only signed, reputable binaries, so
on a machine where it is enabled every invocation dies with [WinError 4551] An Application Control policy has blocked this file. The CLI is not broken; Windows refuses to launch it. Smart App
Control has no per-app allowlist, and turning it off cannot be undone without reinstalling Windows,
so run the Linux CLI inside WSL2 instead and keep the protection on.
Install and authenticate Grok inside the selected distro. Windows CLI login state is not used by this route.
wsl --install -d Ubuntu
wsl -d Ubuntu -- bash -lc "curl -fsSL https://x.ai/cli/install.sh | bash"
wsl -d Ubuntu -- bash -lc "~/.grok/bin/grok login"Example MCP host configuration for this checkout:
{
"mcpServers": {
"xai": {
"command": "C:\\Develop\\XAIMsp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Develop\\XAIMsp\\server.py"],
"env": {
"GROK_WSL_DISTRO": "Ubuntu",
"GROK_CLI_PATH": "/home/segal/.grok/bin/grok"
}
}
}
}Adjust the checkout, distro, and Linux user paths for your installation. With
GROK_WSL_DISTRO set, every call (including grok_version) uses
wsl.exe -d <distro> -- <absolute Linux executable>. GROK_CLI_PATH is required
and must be an absolute Linux path: WSL does not load login-shell PATH settings.
Windows-side executable validation is skipped; WSL reports missing or non-executable binaries.
The distro setting is required; there is no fallback to Windows grok.exe.
Pass workspace as a host path such as C:\Develop\XAIMsp. The bridge converts
drive paths for --cwd and its temporary --prompt-file to /mnt/c/..., assuming
standard WSL drive mounts. Custom mount roots and UNC workspaces are not supported
by this conversion. Prompt files are removed on the host after the call, including failures.
Restart the MCP server after changing its configuration or code. Check grok_version
first, then make a small grok_ask call to verify authentication and model access.
A version check alone does not verify a model response.
Related MCP server: peer-agents-mcp
Install
cd C:\Develop\XAIMsp
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"Use the MCP host configuration in Windows with WSL2. The Python MCP server runs on Windows; all Grok invocations run inside WSL.
Tools
grok_ask(prompt, workspace?, timeout_s?, model?, session_id?, max_turns?, reasoning_effort?, rules?, permission_mode?, raw_output?)grok_continue(prompt, workspace?, timeout_s?, model?, resume?, max_turns?, reasoning_effort?, rules?, permission_mode?, raw_output?)grok_code_review(code_or_diff, question?, primary_analysis?, workspace?, timeout_s?, model?, max_findings?, reasoning_effort?, self_check?, raw_output?)grok_version()
workspace defaults to the MCP server's current directory. Pass the project path explicitly when
you want Grok to inspect a specific repo.
Use grok_code_review as a second-opinion reviewer after the primary or manual analysis. It embeds
strict offline-review rules in the prompt, disables web search, and uses --prompt-file.
Advanced parameters:
model: Defaults togrok-4.6for ask, continue, and review. An explicit model overrides it.permission_mode: Ask/continue acceptacceptEdits,autoorreadOnly.acceptEditsandautoboth send--permission-mode auto, and that is also what a call sends when it passes nothing.readOnlysends no approval flag, so the CLI's own gate stands between Grok and any change, and it appends a rule telling Grok as much so it does not spend turns reaching for tools that will be refused. The gate is the boundary; the rule only saves effort. Other values are rejected. Raw output includes the requested and effective modes.Approval is granted by default because headless grok has nobody to ask. Without it, the first tool call needing a write or a non-read-only command ends the turn as
stopReason: cancelled, returning narration instead of an answer. The grant is real: Grok can write files and run commands in the workspace without asking, and the workspace is a working directory, not a security boundary. Point it at a repository whose changes you can see and revert.max_turns: Defaults to 50. Far above ordinary work, low enough that a stuck loop stops spending quota. Pass a larger value for a genuinely long task.self_check=true: Passes--checkfor an extra Grok verification loop. Use sparingly because it costs more time and quota.raw_output=true: Returns a debug payload with extracted text, stdout, stderr, return code, and parsed JSON when available.session_idandresume: Useful for explicit Grok session control.session_idshould be a valid UUID for new sessions.rules: Available on generic ask/continue calls. Prefergrok_code_reviewfor second-opinion code review because it already uses the tuned offline-review prompt.
Set XAI_MCP_DEBUG=true only when diagnosing bridge startup or CLI invocation issues.
See CLAUDE_CODE_USAGE.md for the recommended Claude Code workflow.
Concurrency
Calls run in parallel, up to MAX_CONCURRENT_GROK (4) at once. Grok sessions are
independent processes -- xAI's own "agent swarm" runs several deliberately -- and
four concurrent calls were measured here returning four correct, uncrossed
answers in 10.4s against 24.8s serialised.
The bound is there because each grok is a ~166MB process and every session draws on the same account pool, so an unbounded burst costs memory and quota rather than time. Anything past the limit waits for a slot; nothing is refused.
An earlier version held a single mutex across every invocation, so a second caller always waited for the first. If you are building anything that fans work out across several calls, that is no longer the constraint it was.
Grok splits work by itself
Before building anything that fans a task out across several grok_ask calls:
Grok already does this internally. Subagents are child sessions with their own
context windows, enabled by default, and the main agent calls spawn_subagent
when it sees work worth delegating. It survives headless invocation through this
bridge -- a request naming three independent questions produced three
spawn_subagent calls, 15 model calls against 3 main-agent turns, and one
combined answer.
So ask for the delegation in the prompt rather than orchestrating it from outside. Splitting into separate bridge calls costs a process each and puts the recombining on the caller, which is work Grok has already done.
Security
Grok is an agentic CLI. workspace is a working directory, not a security boundary. The bridge
does not expose --always-approve through MCP tools. Use grok_code_review with focused snippets
or diffs, and verify findings before editing code.
Smoke Test
This makes a real Grok call and may use quota:
python test_smoke.pyAvailable Tools
4 toolsgrok_askB
Ask Grok a prompt in a new headless CLI session.
Inputs: prompt (required), model, rules, max_turns, +5 more. Returns: result
grok_code_reviewA
Ask Grok for a strict second-opinion code review.
This tool is intended to run after CodeHelper or manual analysis. It sends
strict run-scoped review rules, disables web search, and passes large
prompts via --prompt-file.
Inputs: code_or_diff (required), model, question, timeout_s, +6 more. Returns: result
grok_continueC
Continue a Grok headless session.
If resume is provided, resumes that session id. Otherwise passes
--continue, which continues the most recent session in the workspace.
Inputs: prompt (required), model, rules, resume, +5 more. Returns: result
grok_versionA
Return the installed Grok CLI version.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: general prompting, code review, session continuation, and version checking. No overlap in functionality.
All tools follow a consistent pattern: 'grok_' prefix with snake_case verb or noun suffixes (ask, code_review, continue, version).
4 tools is on the lower end but still appropriate for a focused bridge to a CLI tool. Could be expanded slightly but not under-scoped.
Core operations are covered: prompting, code review, session continuation, and version info. Missing session management or configuration tools but minimal for the domain.
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that wraps the Grok CLI to enable code review, adversarial testing, and chat with xAI's Grok model, integrating into any MCP host as a peer reviewer, adversary, and consultant.4113 npm11MIT
- FlicenseBqualityDmaintenanceEnables AI coding tools to call Grok and Antigravity CLIs as peer reviewers for code review, planning, debugging, and collaborative sessions.13-
- AlicenseNot gradedqualityCmaintenanceEnables Codex to use Grok Build CLI as a controlled subagent via MCP tools for independent investigation, review, and isolated implementation tasks.5MIT
- AlicenseAqualityCmaintenanceExposes the Grok Build CLI as MCP tools for Claude Code and other clients, enabling headless AI agents to perform tasks like code reviews, web research, and file operations with configurable permission levels.887 npmMIT