Skip to main content
Glama
ashwaniarya

grok-web-sdk MCP

by ashwaniarya
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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]"

Related MCP server: dat-ai-mcp

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • grok-build-plugin

    VasiHemanth
    A
    license
    Not graded
    quality
    B
    maintenance
    Live X (Twitter) and web search for any coding agent through your existing Grok subscription. Exposes a grok_search MCP tool, so no X API key or X developer account is needed.
    20 npm
    30
    Apache 2.0

  • Grok Web MCP

    zijueming
    F
    license
    Not graded
    quality
    C
    maintenance
    Automates Grok web interface to provide chat, web search, and conversation management via MCP, supporting multiple accounts and local/remote deployment.
    -