English | Русский

grok-cli-mcp

MCP server for the official Grok CLI — works over OAuth, no API key.

Exposes the grok_query, grok_continue, grok_models and grok_sessions tools to any MCP client (Claude Code, Cline, Cursor, etc.) using your already logged-in Grok account.

---

Requirements

• Python ≥ 3.8
• The grok CLI installed and logged in (grok login, verify with grok models)

---

Installation

cd ~/grok-cli-mcp
pipx install -e . --force

After installation the grok-cli-mcp binary appears on your PATH.

---

Connecting to Claude Code

~/.claude/mcp.json is not read by Claude Code. Register the server via the CLI:

claude mcp add grok --scope user -- grok-cli-mcp

With logging to a file:

claude mcp add grok --scope user -- grok-cli-mcp --log-file ~/grok-mcp.log

Check:

claude mcp list        # grok: grok-cli-mcp - ✔ Connected

Then restart Claude Code so the tools are picked up.

---

Tools

grok_query

Parameter	Type	Description
prompt (required)	string	The prompt text
model	string	Model, e.g. grok-composer-2.5-fast
effort	string	low | medium | high | xhigh | max
reasoning_effort	string	Reasoning effort level
agent	string	Agent name or path to a definition file
permission_mode	string	Permission mode
resume	string	Resume a specific session by ID (see grok_sessions)
max_turns	integer	Maximum number of agent turns
output_format	string	plain | json | streaming-json (default plain)
best_of_n	integer	Run the task N ways in parallel and pick the best (headless)
check	boolean	Append a self-verification loop to the prompt (headless)
sandbox	string	FS/network sandbox profile (from ~/.grok/sandbox.toml)
rules	string	Extra rules to append to the system prompt
allow	string/array	Permission allow rule(s), e.g. Bash(git:*); string or list
deny	string/array	Permission deny rule(s); string or list
tools	string	Built-in tools to allow (comma-separated)
disallowed_tools	string	Built-in tools to remove (comma-separated)
system_prompt_override	string	Override the agent's system prompt
no_plan	boolean	Disable the planning step
no_subagents	boolean	Disable subagents
always_approve	boolean	Auto-approve all tool executions
disable_web_search	boolean	Disable web search / web fetch
cwd	string	Working directory for the session
worktree	string/boolean	New git worktree: a name (string) or true (unnamed)
timeout	number	Max seconds to wait for a response (default 600)

grok_continue

Continues the most recent Grok session for the current working directory with a new prompt (the --continue flag). Same parameters as grok_query, except agent, worktree and resume.

grok_models

No parameters. Returns the list of available models (grok models).

grok_sessions

List or search past Grok sessions. Returns session IDs (for the resume parameter of grok_query) and short summaries.

Parameter	Type	Description
query	string	Search keyword; omit it to list the most recent sessions
limit	integer	Maximum number of sessions to show (default 20)

---

Usage (from Claude Code)

@grok Write a typed function that sums a list

With parameters the tool is called like this:

{
  "prompt": "Write hello world in Python with comments",
  "no_plan": true,
  "output_format": "json"
}

⚠️ Model compatibility. The default model grok-composer-2.5-fast does not support effort / reasoning_effort — a request with them returns an API 400 error. Use them only with reasoning models (grok-build, etc.).

---

Debugging and tests

# Offline tests (unit + protocol, no network and no grok login needed)
python3 -m unittest test_mcp

# + live smoke (actually calls the grok CLI, requires grok login)
GROK_LIVE=1 python3 -m unittest test_mcp

# Run the server manually (talks over stdio, JSON-RPC)
grok-cli-mcp

# With logging
grok-cli-mcp --log-file ~/grok-mcp.log

---

License

MIT © Evgenii Nekrasov