grok-imagine-mcp
An MCP (Model Context Protocol) server that generates images using Grok Imagine. It automates a headless Chromium browser to submit prompts, wait for generation, and save the resulting images to disk.
Features
- Image generation via text prompts with configurable aspect ratios
- Cookie-based authentication -- paste a cURL command from your browser to log in
- Concurrent generation -- up to 4 parallel tabs with automatic queuing for additional requests
- Auto-closing browser -- closes Chromium after 1 minute of inactivity, reopens on next request
- Error handling -- detects rate limits, expired sessions, and sign-in redirects with clear messages
- Stealth mode -- uses
playwright-extrawith stealth plugin to avoid bot detection
Prerequisites
- Bun v1.3+
- A Grok account (free tier works)
Installation
bun install
MCP Configuration
Add the server to your MCP client config (e.g. .cursor/mcp.json):
{
"mcpServers": {
"grok-imagine-mcp": {
"command": "bun",
"args": ["run", "/path/to/grok-imagine-mcp/src/index.ts"]
}
}
}
Set "env": { "DEV": "true" } to run the browser in visible (non-headless) mode for debugging.
Tools
auth
Authenticate with Grok by providing cookies from your browser session.
- Open https://grok.com in your browser (make sure you're logged in)
- Open Developer Tools (F12 or Cmd+Option+I)
- Go to the Network tab
- Refresh the page
- Click on any request to grok.com
- Right-click -> "Copy as cURL"
- Pass the entire curl command to the
authtool
The tool extracts and saves the essential cookies (sso, sso-rw, cf_clearance, x-userid). Cookies persist in data/storage-state.json.
generate_images
Generate images using Grok Imagine.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | Text prompt describing the image(s) to generate |
quantity | number | no | Number of images to save (1-6, default: 1). Each batch produces ~3 images. |
saveFolderFullPath | string | yes | Absolute path to the folder where images will be saved |
aspectRatio | string | no | 2:3, 3:2, 1:1, 9:16, or 16:9 (default: 1:1) |
Images are saved as grok-{timestamp}-{index}.jpg (or .png).
Development
# Run in dev mode (visible browser, file watching)
bun run dev
# Type check
bun run typecheck
# Lint & format
bun run fix
Project Structure
src/
index.ts MCP server entry point and tool registration
browser.ts Browser lifecycle, tab pool, and idle timeout
generate.ts Image generation logic (prompt submission, polling, saving)
chromium.ts Playwright + stealth plugin setup
cookies.ts Cookie parsing, saving, and loading
console.ts Browser console log capture
constants.ts Configuration constants
data/
profile/ Chromium persistent user data
storage-state.json Saved cookies and storage state