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

Related MCP server: Grok Image MCP

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.

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