Grok Mcp

grok-mcp

A Model Context Protocol stdio server that bridges local agents to grok.com using your existing browser session (via cookie header). Install once, register as a local MCP server in your client, and your agent gets access to Grok chat, web search, memory, skills, file uploads, and conversation history — using the same session you already have open in a browser.

> ⚠️ This bridges an undocumented internal web-client API. Everything here > is derived from observed grok.com traffic. Endpoints can (and will) break > when grok.com changes. > For programmatic production access, use xAI's official > api.x.ai instead — it is a separate product and out of > scope for this project.

Why cookie auth (and not the official API)

api.x.ai is a paid per-token product. It does not give you access to your personal grok.com conversation history, persistent memory, the built-in web-search tool, file attachments, or the agent/expert-mode reasoning trace. This project exposes those browser-session-only read/chat features to a local agent, which is something only the web client can do today.

Install

Requires Rust 1.84 or later.

cargo install --git https://github.com/Hirasawa69/grok-mcp --locked

The binary is published as grok-mcp. Confirm the install:

grok-mcp --version

Configure

1. Grab your grok.com cookie

1. Open grok.com in a browser. Make sure you're logged in.
2. Open DevTools → Application → Cookies → https://grok.com.
3. Copy every cookie pair into a single header string:

`` sso=...; sso-rw=...; x-userid=...; cf_clearance=...; __cf_bm=... ` The minimum required pair is sso + sso-rw — the server will fail to start if either is missing. x-userid, cfclearance, and _cf_bm` trigger a warning but are not strictly required.

The cookie header is held in memory only. It is wrapped in a SecretString, never written to logs, and never sent to stdout.

2. Configure via TOML or env

Either drop a TOML file at the platform config dir (~/.config/grok-mcp/config.toml on Linux):

cookie = "sso=...; sso-rw=...; x-userid=...; cf_clearance=...; __cf_bm=..."

[defaults]
mode = "expert"             # "auto" | "expert" | "fast" | any other string
disable_search = false
force_concise = false
disable_memory = false
enable_image_generation = false
image_generation_count = 0
enable_side_by_side = false
disable_text_follow_ups = false

[network]
base_url = "https://grok.com"
user_agent = ""        # use the Chrome-like default
timeout_seconds = 120
stream_idle_timeout_seconds = 60

…or set individual environment variables:

| Variable | Maps to | Notes | |------------------------|---------------------------|-----------------------------------| | GROK_MCP_CONFIG | path to TOML | overrides default config location | | GROK_COOKIE | cookie | full cookie header string | | GROK_MODE | defaults.mode | auto/expert/fast/any string | | GROK_DISABLE_SEARCH | defaults.disable_search | 1/true/0/false | | GROK_FORCE_CONCISE | defaults.force_concise | — | | GROK_DISABLE_MEMORY | defaults.disable_memory | — | | GROK_BASE_URL | network.base_url | for local testing | | GROK_TIMEOUT_SECONDS | network.timeout_seconds | overall request timeout | | RUST_LOG | tracing filter | writes to stderr only |

Precedence, lowest → highest: defaults → TOML file → env vars → runtime mutations via the grok_set_defaults tool (not persisted).

CLI

grok-mcp [-c|--config ] [COMMAND]

Commands:
  serve         Run the MCP stdio server (default when no subcommand is given)
  init-config   Write a starter config TOML with commented defaults
                  --force      overwrite an existing file
  print-config  Resolve the effective config and print it (cookie redacted)
  check-auth    Call /rest/subscriptions and report tier + user id
  list-tools    Print each MCP tool name + description, tab-separated

-c/--config (or GROK_MCP_CONFIG) is global and accepted on every subcommand; passing an explicit path that does not exist is an error.

Typical first-run workflow:

grok-mcp init-config             # drop a starter config at the default path
nano ~/.config/grok-mcp/config.toml   # paste your cookie header
grok-mcp check-auth              # verify cookies, print your tier
grok-mcp                         # start the stdio server (== grok-mcp serve)

Register with an MCP client

Opencode

{
  "mcp": {
    "grok": {
      "type": "local",
      "command": [
        "grok-mcp"
      ],
      "enabled": true
    }
  }
}

Tools

All tools return structured JSON. Names are prefixed with grok_.

| Tool | Description | |---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | grok_research | Hero tool. Deep research via Grok in a single call. Streams the answer and blocks until complete. Use this only for non-expert modes or expert queries you expect to finish inside your MCP client's timeout. Heavy expert queries should use grok_research_start + grok_research_poll instead: if grok_research times out client-side, the answer cannot be recovered. Pass verbosity="minimal" to keep only the final answer + citations, verbosity="standard" (default) for today's streamed payload, or verbosity="full" to hydrate structured steps[] plus agent_messages[] with one extra HTTP round-trip. full_details=true still works as a deprecated alias for verbosity="full". Also accepts per-call connector overrides: enable_gmail_search, enable_google_calendar_search, enable_outlook_search, enable_outlook_calendar_search, and enable_google_drive_search. | | grok_research_start | Begin a long-running Grok research request without waiting for the answer. Returns conversation_id + response_id immediately; use grok_research_poll later to retrieve the result. Prefer this for any expert-mode query or whenever you suspect the run may take more than ~60 seconds, because the job continues on Grok's side even if your client would otherwise time out. | | grok_research_poll | Poll a previously started research result by (conversation_id, response_id). Returns status: "completed" with the full result when ready, status: "in_progress" while Grok is still generating, or status: "not_found" if the id pair is unknown. Pass verbosity="minimal", "standard", or "full" to control payload size. include_thinking=true adds per-step thinking traces separately from the hydrated verbosity="full" fields. | | grok_check_auth | Check that grok.com cookies still work. Returns the logged-in user id, subscription tier, and status. | | grok_rate_limits | Remaining query budget (per-mode rate limit). Defaults to the current runtime mode. | | grok_list_conversations | List grok.com conversations. Pass page_token from a prior response to paginate. | | grok_get_conversation | Fetch a conversation. Set include_messages to also load the full message thread. | | grok_upload_file | Upload a file and get back an attachment id to pass into grok_research. Provide content_base64 or local_path. | | grok_list_skills | List grok.com built-in skills (catalog of tools Grok itself can invoke). | | grok_get_defaults | Read the current runtime defaults (mode + flags).

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Hirasawa69
• Source: Hirasawa69/grok-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.