Grok Image Generation MCP Server

An MCP (Model Context Protocol) server that generates images using Grok's Imagine feature through a Chrome extension bridge. This allows AI assistants like Claude to generate images by automating the Grok Imagine interface.

Architecture

This project consists of two main components:

1. MCP Server (src/)

• MCP Server: Exposes a generate_image tool via the Model Context Protocol (stdio)
• WebSocket Server: Runs on port 3000 to communicate with the Chrome extension
• Image Bridge: Manages request/response flow between MCP and the extension
• Image Storage: Saves generated images to OS temp directory ({tmpdir}/grok-imagine/)

2. Chrome Extension (extension/)

• Background Script: Connects to the WebSocket server at ws://localhost:3000 with keepalive via Chrome alarms
• Content Script: Automates the Grok Imagine interface with localStorage-based aspect ratio control
• Popup UI: Shows connection status and extension information
• Built with React, TypeScript, and TailwindCSS

How It Works

MCP Client (Claude)
    ↓
MCP Server (stdio)
    ↓
WebSocket Server (port 3000)
    ↓
Chrome Extension
    ↓
grok.com/imagine (automation)
    ↓
Chrome Extension (captures image)
    ↓
WebSocket Server
    ↓
MCP Server (saves to temp dir)
    |
MCP Client (receives file paths)

Prerequisites

• Bun v1.3.5 or higher
• Chrome browser
• Grok account (access to grok.com/imagine)

Installation

1. Install MCP Server Dependencies

bun install

2. Install Chrome Extension Dependencies

cd extension
bun install

3. Build the Chrome Extension

cd extension
bun run build

4. Load the Extension in Chrome

1. Open Chrome and navigate to chrome://extensions/
2. Enable "Developer mode" (toggle in the top right)
3. Click "Load unpacked"
4. Select the extension/build directory
5. The extension should now appear in your extensions list

Usage

Running the MCP Server

For development with hot reload:

bun run dev

For production:

bun run build
bun run build/index.js

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grok-imagine": {
      "command": "bun",
      "args": [
        "/absolute/path/to/chrome-extension-mcp/build/index.js"
      ]
    }
  }
}

Replace /absolute/path/to/chrome-extension-mcp with the actual path to this project.

Generating Images

Once configured, you can ask Claude to generate images:

Generate an image of a sunset over mountains

The generate_image tool supports the following parameters:

• prompt (required): Text description of the image to generate
• aspectRatio (optional): One of "1:1", "3:2", "2:3", "16:9", "9:16" (default: "1:1")
• imageCount (optional): Number of images to generate, "1" to "4" (default: "1")

Claude will use the generate_image tool, which will:

1. Send a request to the Chrome extension via WebSocket
2. The extension opens grok.com/imagine in a new tab
3. Sets the correct aspect ratio (reloads page if needed)
4. Automates entering the prompt and generating the image(s)
5. Captures the generated image(s) as base64
6. Closes the tab and sends the images back
7. The MCP server saves images to the OS temp directory ({tmpdir}/grok-imagine/)
8. Returns the file paths to the MCP client

Development

Project Structure

chrome-extension-mcp/
├── src/                          # MCP Server source code
│   ├── index.ts                  # Entry point
│   ├── mcpServer.ts              # MCP server with generate_image tool
│   ├── webServer.ts              # WebSocket server (port 3000)
│   ├── imageRequestBridge.ts     # Request/response management
│   └── imageStorage.ts           # Image saving logic (saves to temp dir)
├── extension/                    # Chrome Extension
│   ├── src/
│   │   ├── background.ts         # Background script (WebSocket client with keepalive)
│   │   ├── contentScript.ts      # Grok automation script
│   │   ├── types.ts              # Type definitions
│   │   ├── utils.ts              # Utility functions
│   │   ├── popup/                # Popup UI (React)
│   │   └── options/              # Options page (React)
│   ├── public/                   # Extension assets (manifest, HTML, icons)
│   ├── config/                   # Build scripts
│   └── build/                    # Built extension (load this in Chrome)
├── build/                        # Built MCP server
├── package.json                  # MCP server dependencies
└── tsconfig.json                 # TypeScript configuration

Available Scripts

MCP Server (root directory)

bun run dev          # Run with hot reload
bun run build        # Build for production
bun run lint         # Lint code
bun run format       # Format code
bun run typecheck    # Type check
bun run fix          # Lint, format, and type check

Chrome Extension (extension directory)

bun run dev          # Development build with watch mode
bun run build        # Production build
bun run pack         # Package for Chrome Web Store
bun run lint         # Lint code
bun run format       # Format code
bun run typecheck    # Type check
bun run fix          # Lint, format, and type check

Configuration

Environment Variables

You can configure the MCP server behavior using environment variables:

• IMAGE_REQUEST_TIMEOUT: Timeout for image generation requests in milliseconds (default: 60000)

Extension Settings

The Chrome extension connects to ws://localhost:3000 by default. If you need to change this, modify extension/src/background.ts.

Troubleshooting

Extension Not Connecting

1. Make sure the MCP server is running
2. Check that the WebSocket server is listening on port 3000
3. Look at the Chrome extension console (background script) for connection errors
4. Try disconnecting and reconnecting by reloading the extension

Image Generation Fails

1. Ensure you're logged into grok.com in Chrome
2. Check that you have access to Grok Imagine
3. Look at the console logs in both the MCP server and Chrome extension
4. Verify that the content script is properly injecting into grok.com/imagine

MCP Tool Not Appearing in Claude

1. Verify the config file path is correct
2. Restart Claude Desktop
3. Check the path to the built server is absolute
4. Look at Claude Desktop logs for errors

License

This project is licensed under the MIT License - see the extension/license file for details.

Tech Stack

• Runtime: Bun
• MCP SDK: @modelcontextprotocol/sdk
• Chrome Extension: Manifest V3
• Frontend: React, TypeScript, TailwindCSS
• Linting: BiomeJS
• Communication: WebSocket (native Bun.serve)

Contributing

Contributions are welcome! Please ensure your code:

• Passes all linting and type checking (bun run fix)
• Follows the existing code style
• Includes appropriate error handling
• Updates documentation as needed