The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Grok Image listing page.
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.
| Tool | Description |
|---|---|
generate_image | Generate an image from a text prompt |
edit_image | Edit an existing image using natural language instructions |
headshot | Corporate headshot from a source portrait (pad to 3:2 + fixed edit prompt) |
list_styles | List available image styles for use with generate_image |
Generate an image from a text description.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | Text description of the desired image |
model | string | no | Model to use (default: grok-imagine-image-2.0) |
n | integer | no | Number of images to generate (1-10, default 1) |
aspect_ratio | string | no | Aspect ratio: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, 21:9, 5:2, auto |
resolution | string | no | Output resolution: 1k (~1024px, default) or 2k (~2048px) |
quality | string | no | low, medium, or auto (2.0 only; omitted = auto. Auto currently serves low for generation) |
response_format | string | no | Output format: url (default, temporary) or b64_json |
style | string | no | Style name to apply (use list_styles to see options) |
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 an existing image using natural language instructions.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
image_url | string | no* | URL, base64 data URI, or local file path of the source image. Mutually exclusive with images. |
images | string[] | no* | Up to 5 source images for multi-image editing. Reference them in the prompt as <IMAGE_0>, <IMAGE_1>, … |
prompt | string | yes | Natural language edit instructions |
model | string | no | Model to use (default: grok-imagine-image-2.0) |
n | integer | no | Number of variations to generate (1-10, default 1) |
aspect_ratio | string | no | Same set as generate_image, including 21:9 and 5:2 |
resolution | string | no | Output resolution: 1k (~1024px, default) or 2k (~2048px) |
quality | string | no | low, medium, or auto (2.0 only; omitted = auto. Auto currently serves medium for editing) |
response_format | string | no | Output format: url (default, temporary) or b64_json |
* 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.
Expand-only portrait fix (Gemini pipeline equivalent on Imagine). Does not reframe pose, cut out hair, or redesign the person.
grok-imagine-image-2.0 at quality medium: complete cut-off shoulders if needed; clean solid white background; keep face/hair/pose/clothing/logosNo cutout / no rembg / no transparent alpha — same job as the original Gemini headshot skill.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
image | string | yes | Local path, http(s) URL, or data: URI |
clothing | string | no | For missing-shoulder fill only |
notes | string | no | Must-preserve details (glasses, exact logo text, …) |
pronoun | string | no | his / her / their (default their) |
gravity | string | no | Letterbox gravity (North default) |
content_width | integer | no | Resize width before pad (default 550) |
canvas_width | integer | no | Padded width (default 780) |
resolution | string | no | 1k or 2k (default 2k) |
output_path | string | no | Optional final path (also under save_dir) |
n | integer | no | Variations (1–10, default 1) |
quality | string | no | low / medium / auto (default medium) |
model | string | no | Default grok-imagine-image-2.0 |
Padded intermediate: save_dir/headshot-padded_*.jpg.
Returns all available image styles with their name, description, and prompt template. No parameters.
| Style | Description |
|---|---|
watercolor | Watercolor painting style |
oil-painting | Oil painting with visible brushstrokes |
pencil-sketch | Detailed pencil sketch |
pixel-art | Retro pixel art |
anime | Anime style illustration |
pop-art | Bold pop art style |
art-nouveau | Art nouveau with flowing organic lines |
cinematic | Cinematic photography with dramatic lighting |
portrait | Professional portrait photography |
macro | Extreme macro photography |
aerial | Aerial drone photography |
studio | Studio photography on clean background |
noir | Dark film noir style |
vintage | Faded vintage photograph |
| Model | Notes |
|---|---|
grok-imagine-image-2.0 (default) | Optional quality (low / medium / auto), up to 5 edit references, 21:9 and 5:2. Auto currently serves low for generation and medium for editing. |
grok-imagine-image | 1.0. Still available; no quality param. |
grok-imagine-image-quality | Retires 2026-11-02. After that the slug is served by grok-imagine-image-2.0 at quality: low ($0.01 less per image than the quality model). |
Create the config file:
Create ~/.config/mcp-server-grok-image/config.toml:
Add custom styles to your config file. Custom styles with the same name as a built-in will override it.
Templates must contain the {prompt} placeholder. Any custom style missing it will be skipped with a warning at startup.
This produces target/release/mcp-server-grok-image.
For development:
Add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json):
MIT