Grok Image MCP

Servidor MCP para geração e edição de imagens Grok

Documentação

mcp-server-grok-image

Um servidor MCP (Model Context Protocol) para a API de geração de imagens Grok da xAI. Construído em Rust, expõe geração e edição de imagens como ferramentas MCP.

Comunica via stdio usando JSON-RPC 2.0, como todos os servidores MCP.

Ferramentas

Ferramenta	Descrição
`generate_image`	Gera uma imagem a partir de um prompt de texto
`edit_image`	Edita uma imagem existente usando instruções em linguagem natural
`headshot`	Retrato corporativo a partir de uma foto de origem (com padding 3:2 + prompt de edição fixo)
`list_styles`	Lista estilos de imagem disponíveis para uso com `generate_image`

generate_image

Gera uma imagem a partir de uma descrição em texto.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
`prompt`	string	sim	Descrição em texto da imagem desejada
`model`	string	não	Modelo a usar (padrão: `grok-imagine-image-2.0`)
`n`	inteiro	não	Número de imagens a gerar (1-10, padrão 1)
`aspect_ratio`	string	não	Proporção 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	não	Resolução de saída: `1k` (~1024px, padrão) ou `2k` (~2048px)
`quality`	string	não	`low`, `medium` ou `auto` (apenas 2.0; omitido = `auto`. Auto atualmente serve `low` para geração)
`response_format`	string	não	Formato de saída: `url` (padrão, temporário) ou `b64_json`
`style`	string	não	Nome do estilo a aplicar (use `list_styles` para ver as opções)

Quando um estilo é definido, o prompt é envolvido no template do estilo. Por exemplo, com style: "watercolor" e prompt: "a cat on a roof", a API recebe "a cat on a roof, as a watercolor painting". Evite incluir linguagem de estilo no próprio prompt ao usar este parâmetro.

A resposta inclui o prompt resolvido para que você possa ver exatamente o que foi enviado à API.

edit_image

Edita uma imagem existente usando instruções em linguagem natural.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
`image_url`	string	não*	URL, data URI base64 ou caminho de arquivo local da imagem de origem. Mutuamente exclusivo com `images`.
`images`	string[]	não*	Até 5 imagens de origem para edição multi-imagem. Referencie-as no prompt como `<IMAGE_0>`, `<IMAGE_1>`, …
`prompt`	string	sim	Instruções de edição em linguagem natural
`model`	string	não	Modelo a usar (padrão: `grok-imagine-image-2.0`)
`n`	inteiro	não	Número de variações a gerar (1-10, padrão 1)
`aspect_ratio`	string	não	Mesmo conjunto de `generate_image`, incluindo `21:9` e `5:2`
`resolution`	string	não	Resolução de saída: `1k` (~1024px, padrão) ou `2k` (~2048px)
`quality`	string	não	`low`, `medium` ou `auto` (apenas 2.0; omitido = `auto`. Auto atualmente serve `medium` para edição)
`response_format`	string	não	Formato de saída: `url` (padrão, temporário) ou `b64_json`

* Forneça image_url ou images.

Nota: O parâmetro style está intencionalmente indisponível em edit_image — prompts de edição são instruções (ex.: "remova o fundo"), não descrições, então envolvê-los em templates de estilo produziria algo sem sentido.

headshot

Correção de retrato somente expansão (equivalente ao pipeline Gemini no Imagine). Não reenquadra pose, recorta cabelo ou redesenha a pessoa.

Redimensiona a fonte completa (padrão 550px de largura) — nunca corta
Letterbox com margens brancas até a largura do canvas (padrão 780)
Chama grok-imagine-image-2.0 em qualidade média: completa ombros cortados se necessário; limpa fundo branco sólido; mantém rosto/cabelo/pose/roupas/logos

Sem recorte / sem rembg / sem alpha transparente — mesmo trabalho da skill original de headshot do Gemini.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
`image`	string	sim	Caminho local, URL http(s) ou URI `data:`
`clothing`	string	não	Apenas para preenchimento de ombros ausentes
`notes`	string	não	Detalhes que devem ser preservados (óculos, texto exato do logo, …)
`pronoun`	string	não	`his` / `her` / `their` (padrão `their`)
`gravity`	string	não	Gravidade do letterbox (padrão `North`)
`content_width`	inteiro	não	Largura de redimensionamento antes do padding (padrão `550`)
`canvas_width`	inteiro	não	Largura com padding (padrão `780`)
`resolution`	string	não	`1k` ou `2k` (padrão `2k`)
`output_path`	string	não	Caminho final opcional (também em `save_dir`)
`n`	inteiro	não	Variações (1–10, padrão 1)
`quality`	string	não	`low` / `medium` / `auto` (padrão `medium`)
`model`	string	não	Padrão `grok-imagine-image-2.0`

Intermediário com padding: save_dir/headshot-padded_*.jpg.

list_styles

Retorna todos os estilos de imagem disponíveis com nome, descrição e template de prompt. Sem parâmetros.

Estilos Integrados

Estilo	Descrição
`watercolor`	Estilo de pintura em aquarela
`oil-painting`	Pintura a óleo com pinceladas visíveis
`pencil-sketch`	Esboço detalhado a lápis
`pixel-art`	Pixel art retrô
`anime`	Ilustração em estilo anime
`pop-art`	Estilo pop art ousado
`art-nouveau`	Art nouveau com linhas orgânicas fluidas
`cinematic`	Fotografia cinematográfica com iluminação dramática
`portrait`	Fotografia profissional de retrato
`macro`	Fotografia macro extrema
`aerial`	Fotografia aérea com drone
`studio`	Fotografia de estúdio com fundo limpo
`noir`	Estilo noir de filme escuro
`vintage`	Fotografia vintage desbotada

Modelos Disponíveis

Modelo	Notas
`grok-imagine-image-2.0` (padrão)	`quality` opcional (`low` / `medium` / `auto`), até 5 referências de edição, `21:9` e `5:2`. Auto atualmente serve `low` para geração e `medium` para edição.
`grok-imagine-image`	1.0. Ainda disponível; sem parâmetro `quality`.
`grok-imagine-image-quality`	Aposenta em 2026-11-02. Depois disso, o slug é servido por `grok-imagine-image-2.0` a `quality: low` ($0,01 a menos por imagem que o modelo de qualidade).

Pré-requisitos

Rust (edição 2024)
Uma chave de API xAI de console.x.ai

Configuração

Crie o arquivo de configuração:

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

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

api_key = "xai-..."

Estilos Personalizados

Adicione estilos personalizados ao seu arquivo de configuração. Estilos personalizados com o mesmo nome de um estilo integrado o substituirão.

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 devem conter o placeholder {prompt}. Qualquer estilo personalizado sem ele será ignorado com um aviso na inicialização.

Build

cargo build --release

Isso produz target/release/mcp-server-grok-image.

Para desenvolvimento:

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

Configuração MCP

Adicione à configuração do seu Claude Desktop (~/.config/Claude/claude_desktop_config.json):

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

Estrutura do Projeto

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

Licença

MIT