grok-web-sdk

Drive your own Grok to generate content — text, images, video — from a local AI agent, the command line, HTTP, or Python. It automates the grok.com web UI using your logged-in session, so there's no API key and no per-token cost.

Runs locally by default: patchright drives a real Chrome on your machine (no Docker). A Browserless backend is available for remote/scale use.

flowchart LR
  Agent[Local AI agent] -->|MCP| M[grok mcp]
  You -->|CLI| C[grok chat / image / video]
  M --> B[behaviours]
  C --> B
  B --> Chrome[local Chrome<br/>your logged-in Grok]
  Chrome --> Out[text · images · video → files]

Install

With pipx (recommended — installs a global grok command in its own env):

pipx install grok-web-sdk         # once published to PyPI
# …or from a local checkout today:
pipx install ./grok-web-sdk
grok install-browser              # only if you don't have Google Chrome

From source (for development):

git clone <this repo> && cd grok-web-sdk
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Sign in once

grok login

A Chrome window opens — log into your Grok account, press Enter. The session persists in a local profile (~/.grok-web-sdk/profile), so you only do this once (repeat if it ever expires).

Use it

CLI

grok chat "explain quantum tunneling in one paragraph"
grok image "a red teapot on the moon" --aspect 16:9 --count 4 -o ./out
grok video "a paper plane looping" --res 720p --duration 10s -o ./out

Image/video files are downloaded to ./downloads (or -o <dir>) and the paths are printed.

MCP (local AI agents) — expose Grok as tools to Claude Desktop, Claude Code, Cline, Cursor, etc.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "grok": { "command": "/absolute/path/to/.venv/bin/grok", "args": ["mcp"] }
  }
}

Claude Code:

claude mcp add grok -- /absolute/path/to/.venv/bin/grok mcp

Tools: grok_chat, grok_generate_image, grok_generate_video — image/video tools return the saved file paths.

HTTP API

grok serve --port 8000
# POST /chat/messages · POST /imagine/images · POST /imagine/videos · GET /health

Python

from grok_web_sdk import grok_context, send_message, generate_image, generate_video

with grok_context() as ctx:                      # local backend by default
    print(send_message(ctx, "hello").response)
    img = generate_image(ctx, "a red teapot", aspect_ratio="1:1", count="4")
    print(img.files)                             # downloaded paths

Capabilities

Surface	Options
Chat	prompt → reply (+ reasoning header)
Image	quality Speed/Quality · aspect_ratio 2:3·3:2·1:1·9:16·16:9 · count Auto·4·8·12
Video	resolution 480p·720p · duration 6s·10s · aspect_ratio

Remote backend (optional)

To run against a Browserless container instead of local Chrome:

from grok_web_sdk import grok_context, BrowserlessConfig
with grok_context(BrowserlessConfig(url="ws://host:3000", token="…")) as ctx:
    ...

From a datacenter IP you'll also need a residential proxy (proxy= on the config) — Cloudflare weighs IP reputation separately from browser fingerprint.

Tests

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                                          # unit + contract, no browser; live tier auto-skips
GROK_PROFILE_DIR=spike/.profile .venv/bin/pytest -m live  # read-only live tier (needs a logged-in profile)

Notes

• Your account, your rules. This automates the web UI with your session; that likely runs against xAI's ToS. Use a dedicated/throwaway account if you're cautious, and keep request rates sane.
• Local-first & private. Everything runs on your machine; the session profile and downloads never leave it.
• Architecture: core → pages (L1) → behaviours (L2) → api (MCP/HTTP/CLI), enforced by import-linter.