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-extra with 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.

1. Open https://grok.com in your browser (make sure you're logged in)
2. Open Developer Tools (F12 or Cmd+Option+I)
3. Go to the Network tab
4. Refresh the page
5. Click on any request to grok.com
6. Right-click -> "Copy as cURL"
7. Pass the entire curl command to the auth tool

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