Metadata-Version: 2.4
Name: grok-cli-mcp-server
Version: 1.0.0
Summary: MCP server for the official Grok CLI (OAuth, no API key)
Author-email: Evgenii Nekrasov <evgeniy@nekrasov.pw>
License: MIT
Project-URL: Homepage, https://github.com/Ravino/grok-cli-mcp
Project-URL: Repository, https://github.com/Ravino/grok-cli-mcp
Project-URL: Issues, https://github.com/Ravino/grok-cli-mcp/issues
Keywords: mcp,grok,xai,llm,cli,claude,ai,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

**English** | [Русский](README.ru.md)

# 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

```bash
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:

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

With logging to a file:

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

Check:

```bash
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:

```json
{
  "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

```bash
# 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](LICENSE) © Evgenii Nekrasov
