mcp-server-grok-image

An MCP (Model Context Protocol) server for xAI's Grok image generation API. Built in Rust, exposes image generation and editing as MCP tools.

Communicates via stdio using JSON-RPC 2.0, like all MCP servers.

Tools

generate_image

Generate an image from a text description.

Parameters:

When a style is set, the prompt is wrapped in the style's template. For example, with `style: "watercolor"` and `prompt: "a cat on a roof"`, the API receives `"a cat on a roof, as a watercolor painting"`. Avoid including style language in the prompt itself when using this parameter.

The response includes the resolved prompt so you can see exactly what was sent to the API.

edit_image

Edit an existing image using natural language instructions.

Parameters:

\* Provide either `image_url` or `images`.

Note: The `style` parameter is intentionally not available on `edit_image` -- edit prompts are instructions (e.g. "remove the background"), not descriptions, so wrapping them in style templates would produce nonsense.

headshot

Expand-only portrait fix (Gemini pipeline equivalent on Imagine). Does not reframe pose, cut out hair, or redesign the person.

1. Resize full source (default 550px wide) — never crop

2. Letterbox with white gutters to canvas width (default 780)

3. Call `grok-imagine-image-2.0` at quality medium: complete cut-off shoulders if needed; clean solid white background; keep face/hair/pose/clothing/logos

No cutout / no rembg / no transparent alpha — same job as the original Gemini headshot skill.

Parameters:

Padded intermediate: `save_dir/headshot-padded_*.jpg`.

list_styles

Returns all available image styles with their name, description, and prompt template. No parameters.

Built-in Styles

Available Models

Prerequisites

• Rust (edition 2024)
• An xAI API key from console.x.ai

Setup

Create the config file:

mkdir -p ~/.config/mcp-server-grok-image

Create `~/.config/mcp-server-grok-image/config.toml`:

api_key = "xai-..."

Custom Styles

Add custom styles to your config file. Custom styles with the same name as a built-in will override it.

api_key = "xai-..."

[[styles]]
name = "my-style"
description = "My custom look"
template = "{prompt}, in my custom style"

[[styles]]
name = "watercolor"
description = "My watercolor variant"
template = "{prompt}, as a loose expressive watercolor with ink outlines"

Templates must contain the `{prompt}` placeholder. Any custom style missing it will be skipped with a warning at startup.

Build

cargo build --release

This produces `target/release/mcp-server-grok-image`.

For development:

cargo build              # debug build
cargo run                # run in dev mode
RUST_LOG=debug cargo run # run with debug logging

MCP Configuration

Add to your Claude Desktop config (`~/.config/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "grok-image": {
      "command": "/path/to/mcp-server-grok-image"
    }
  }
}

Project Structure

src/
  main.rs      process entry (stdio MCP)
  config.rs    TOML / env config
  styles.rs    built-in + custom styles
  grok.rs      xAI request/response types
  params.rs    MCP tool params + validation
  image_io.rs  data URIs, local files, mime, fetch
  headshot.rs  letterbox pad + expand prompt
  server.rs    MCP tools and Grok HTTP

License

MIT