Grok Image MCP

mcp-server-grok-image

Un servidor MCP (Model Context Protocol) para la API de generación de imágenes de xAI Grok. Construido en Rust, expone la generación y edición de imágenes como herramientas MCP.

Se comunica a través de stdio usando JSON-RPC 2.0, como todos los servidores MCP.

Herramientas

Herramienta	Descripción
generate_image	Genera una imagen a partir de un prompt de texto
edit_image	Edita una imagen existente usando instrucciones en lenguaje natural
headshot	Retrato corporativo a partir de un retrato fuente (con relleno a 3:2 + prompt de edición fijo)
list_styles	Lista los estilos de imagen disponibles para usar con generate_image

generate_image

Genera una imagen a partir de una descripción de texto.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
prompt	string	sí	Descripción de texto de la imagen deseada
model	string	no	Modelo a usar (predeterminado: grok-imagine-image-2.0)
n	integer	no	Número de imágenes a generar (1-10, predeterminado 1)
aspect_ratio	string	no	Relación de aspecto: 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	Resolución de salida: 1k (~1024px, predeterminado) o 2k (~2048px)
quality	string	no	low, medium o auto (solo 2.0; omitido = auto. Auto actualmente sirve low para generación)
response_format	string	no	Formato de salida: url (predeterminado, temporal) o b64_json
style	string	no	Nombre del estilo a aplicar (usa list_styles para ver las opciones)

Cuando se establece un estilo, el prompt se envuelve en la plantilla del estilo. Por ejemplo, con style: "watercolor" y prompt: "a cat on a roof", la API recibe "a cat on a roof, as a watercolor painting". Evita incluir lenguaje de estilo en el prompt mismo cuando uses este parámetro.

La respuesta incluye el prompt resuelto para que puedas ver exactamente lo que se envió a la API.

edit_image

Edita una imagen existente usando instrucciones en lenguaje natural.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
image_url	string	no*	URL, data URI en base64 o ruta de archivo local de la imagen fuente. Mutuamente excluyente con images.
images	string[]	no*	Hasta 5 imágenes fuente para edición multi-imagen. Refiérelas en el prompt como <IMAGE_0>, <IMAGE_1>, …
prompt	string	sí	Instrucciones de edición en lenguaje natural
model	string	no	Modelo a usar (predeterminado: grok-imagine-image-2.0)
n	integer	no	Número de variaciones a generar (1-10, predeterminado 1)
aspect_ratio	string	no	Mismo conjunto que generate_image, incluyendo 21:9 y 5:2
resolution	string	no	Resolución de salida: 1k (~1024px, predeterminado) o 2k (~2048px)
quality	string	no	low, medium o auto (solo 2.0; omitido = auto. Auto actualmente sirve medium para edición)
response_format	string	no	Formato de salida: url (predeterminado, temporal) o b64_json

* Proporciona image_url o images.

Nota: El parámetro style no está disponible intencionalmente en edit_image — los prompts de edición son instrucciones (p. ej., "elimina el fondo"), no descripciones, por lo que envolverlos en plantillas de estilo produciría resultados sin sentido.

headshot

Corrección de retrato solo expansión (equivalente al pipeline de Gemini en Imagine). No reencuadra la pose, no recorta el cabello ni rediseña a la persona.

1. Redimensiona la fuente completa (ancho predeterminado 550px) — nunca recorta
2. Añade barras blancas a los lados hasta el ancho del lienzo (predeterminado 780)
3. Llama a grok-imagine-image-2.0 con calidad media: completa los hombros cortados si es necesario; limpia el fondo blanco sólido; conserva cara/cabello/pose/ropa/logotipos

Sin recorte / sin rembg / sin alfa transparente — mismo trabajo que la habilidad original de retrato de Gemini.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
image	string	sí	Ruta local, URL http(s) o URI data:
clothing	string	no	Solo para relleno de hombros faltantes
notes	string	no	Detalles que deben conservarse (gafas, texto exacto del logotipo, …)
pronoun	string	no	his / her / their (predeterminado their)
gravity	string	no	Gravedad del relleno lateral (North predeterminado)
content_width	integer	no	Ancho de redimensionado antes del relleno (predeterminado 550)
canvas_width	integer	no	Ancho con relleno (predeterminado 780)
resolution	string	no	1k o 2k (predeterminado 2k)
output_path	string	no	Ruta final opcional (también bajo save_dir)
n	integer	no	Variaciones (1–10, predeterminado 1)
quality	string	no	low / medium / auto (predeterminado medium)
model	string	no	Predeterminado grok-imagine-image-2.0

Intermedio con relleno: save_dir/headshot-padded_*.jpg.

list_styles

Devuelve todos los estilos de imagen disponibles con su nombre, descripción y plantilla de prompt. Sin parámetros.

Estilos Integrados

Estilo	Descripción
watercolor	Estilo de pintura a acuarela
oil-painting	Pintura al óleo con pinceladas visibles
pencil-sketch	Boceto detallado a lápiz
pixel-art	Arte pixelado retro
anime	Ilustración estilo anime
pop-art	Estilo pop art audaz
art-nouveau	Art nouveau con líneas orgánicas fluidas
cinematic	Fotografía cinematográfica con iluminación dramática
portrait	Fotografía de retrato profesional
macro	Fotografía macro extrema
aerial	Fotografía aérea con dron
studio	Fotografía de estudio sobre fondo limpio
noir	Estilo noir cinematográfico oscuro
vintage	Fotografía vintage desvanecida

Modelos Disponibles

Modelo	Notas
grok-imagine-image-2.0 (predeterminado)	quality opcional (low / medium / auto), hasta 5 referencias de edición, 21:9 y 5:2. Auto actualmente sirve low para generación y medium para edición.
grok-imagine-image	1.0. Aún disponible; sin parámetro quality.
grok-imagine-image-quality	Se retira el 2026-11-02. Después de eso, el slug es servido por grok-imagine-image-2.0 a quality: low ($0.01 menos por imagen que el modelo de calidad).

Requisitos previos

• Rust (edición 2024)
• Una clave de API de xAI de console.x.ai

Configuración

Crea el archivo de configuración:

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

Crea ~/.config/mcp-server-grok-image/config.toml:

api_key = "xai-..."

Estilos Personalizados

Añade estilos personalizados a tu archivo de configuración. Los estilos personalizados con el mismo nombre que uno integrado lo sobrescribirán.

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"

Las plantillas deben contener el marcador de posición {prompt}. Cualquier estilo personalizado que no lo tenga se omitirá con una advertencia al inicio.

Compilación

cargo build --release

Esto produce target/release/mcp-server-grok-image.

Para desarrollo:

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

Configuración MCP

Añade a la configuración de tu Claude Desktop (~/.config/Claude/claude_desktop_config.json):

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

Estructura del Proyecto

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

Licencia

MIT