# grok-imagine-mcp

An MCP (Model Context Protocol) server that generates images using [Grok Imagine](https://grok.com/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](https://bun.sh) v1.3+
- A Grok account (free tier works)

## Installation

```bash
bun install
```

## MCP Configuration

Add the server to your MCP client config (e.g. `.cursor/mcp.json`):

```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

```bash
# 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
```