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
| Tool | Description |
|---|---|
generate_image | Generate an image from a text prompt |
edit_image | Edit an existing image using natural language instructions |
list_styles | List available image styles for use with generate_image |
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) |
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, auto, etc. |
resolution | string | no | Output resolution: 1k (~1024px, default) or 2k (~2048px) |
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_image
Edit an existing image using natural language instructions.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
image_url | string | yes | URL, base64 data URI, or local file path of the source image |
prompt | string | yes | Natural language edit instructions |
model | string | no | Model to use (default: grok-imagine-image) |
n | integer | no | Number of variations to generate (1-10, default 1) |
resolution | string | no | Output resolution: 1k (~1024px, default) or 2k (~2048px) |
response_format | string | no | Output format: url (default, temporary) or b64_json |
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.
list_styles
Returns all available image styles with their name, description, and prompt template. No parameters.
Built-in Styles
| 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 |
Available Models
| Model | Resolution | Cost | Rate Limit |
|---|---|---|---|
grok-imagine-image (default) | 1k/2k | $0.02/image | 300 RPM |
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 - everything: config, styles, API types, MCP server, tool definitions
License
MIT