README.md
Automates a headless Chromium browser to generate images using Grok Imagine
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
Tools (2)
authAuthenticate with Grok by providing cookies from your browser session.generate_imagesGenerate images using Grok Imagine.Environment Variables
DEVSet to 'true' to run the browser in visible (non-headless) mode for debugging.Configuration
claude_desktop_config.json
{
"mcpServers": {
"grok-imagine-mcp": {
"command": "bun",
"args": ["run", "/path/to/grok-imagine-mcp/src/index.ts"]
}
}
}Try it
→Generate a 16:9 image of a futuristic city skyline at sunset and save it to /Users/me/images.
→Create 3 images of a cute robot reading a book in a library.
→Generate a square image of a mountain landscape with a lake in the foreground.
→Authenticate the Grok session using the provided cURL command.