Image Generator

Geração e edição de imagens com recursos avançados como mesclagem de múltiplas imagens e consistência

Documentação

MCP Image Generator 🍌

Gere e edite imagens a partir do Cursor, Claude Code, Codex ou qualquer ferramenta compatível com MCP. Suporta Google Gemini, OpenAI GPT Image e BytePlus Seedream.

Este servidor MCP transforma uma solicitação em linguagem natural em um arquivo de imagem. Ele adiciona detalhes fotográficos relevantes, como iluminação, ângulo de câmera, materiais e paleta de cores, e então retorna a imagem salva como um recurso MCP.

Como Funciona

You: "a roast chicken for a recipe page, partway through
      carving so you can see how juicy it is"
        ↓
  Your AI assistant sends the request to mcp-image
        ↓
  Prompt enhancement adds relevant photographic details
  (subject, lighting, camera, and palette)
        ↓
  The selected provider generates the image
  (using the configured grounding, consistency, and resolution options)
        ↓
  Saved file, returned as an MCP resource

Seu assistente de IA fornece o estilo, o propósito e o contexto da sua solicitação. O mcp-image preenche os detalhes visuais ausentes e seleciona as configurações de geração.

O otimizador de prompt usa uma estrutura Assunto–Contexto–Estilo. Ele roda no Gemini 2.5 Flash por padrão, no OpenAI Responses quando IMAGE_PROVIDER=openai, ou no ModelArk Responses quando IMAGE_PROVIDER=seedream. Ele adiciona detalhes ausentes sobre o assunto, ambiente, iluminação e trabalho de câmera, mantendo os detalhes já presentes na solicitação. Prompts detalhados recebem menos alterações.

Exemplo

Você escreve: "uma foto de um jantar de frango assado para um site de receitas. deve parecer que foi realmente cozido, e deve estar parcialmente sendo cortado para que você possa ver o quão suculento é"

O que o servidor envia para o modelo de imagem: "...um frango inteiro lindamente assado, dourado e brilhante, descansando em uma tábua de corte rústica de madeira. Uma perna está parcialmente cortada, revelando carne branca macia e suculenta e sucos ricos e brilhantes se acumulando ao redor da faca de cortar ... profundidade de campo rasa para manter o foco nitidamente no frango cortado."

Roast chicken, generated with prompt optimization

Provedor Gemini, predefinição padrão fast.

O que foi mantido:

for a recipe site → um assunto, com todo o resto mantido subordinado
actually cooked → sucos espalhados pela tábua, douramento irregular
partway through being carved → a superfície cortada, com fatias colocadas ao lado
how juicy it is → enquadramento próximo e profundidade de campo rasa no corte

A mesma solicitação e configurações, sem otimização de prompt

The same request with prompt optimization disabled

Defina SKIP_PROMPT_ENHANCEMENT=true para enviar seu prompt sem alterações.

Recursos

Aprimoramento de prompt: Adiciona detalhes de iluminação, composição, câmera e paleta usando o modelo de texto do provedor selecionado.
Provedores de imagem: Defina IMAGE_PROVIDER=openai para OpenAI GPT Image ou IMAGE_PROVIDER=seedream para BytePlus Seedream via ModelArk. Passe provider em uma única solicitação para alternar provedores sem alterar a configuração do servidor.
Predefinições de qualidade: Selecione fast, balanced ou quality. Cada provedor mapeia esses valores para uma rota de modelo suportada. Consulte Predefinições de Qualidade.
Edição de imagens: Edite uma imagem existente com instruções em linguagem natural, mantendo seu estilo e detalhes visuais.
Controles de resolução: Solicite até 4K, dependendo do provedor e da rota de qualidade.
Proporções de aspecto: Suporta formatos de quadrado (1:1) a ultra-largo (21:9) e ultra-alto (1:8).
Consistência de personagem: Mantenha a aparência de um personagem consistente em storyboards, fotos de produto ou uma série de imagens.
Opções específicas do provedor:
- Fundamentação do Google Search para precisão factual em tempo real com o provedor Gemini
- Conhecimento mundial para representações fotorrealistas de figuras históricas, marcos e cenários factuais
- Orientação de mesclagem em nível de prompt para cenas compostas
- Geração consciente do propósito (por exemplo, "capa de livro de receitas" produz resultados diferentes de "postagem em mídia social")
Formatos de saída: OpenAI e Seedream suportam seleção de PNG ou JPEG através do nome do arquivo de saída.

Pré-requisitos

Node.js 22 ou superior
Chave de API do Gemini - Obtenha a sua no Google AI Studio para o provedor Gemini padrão
Chave de API da OpenAI - Obtenha a sua na OpenAI ao usar IMAGE_PROVIDER=openai
Chave de API do BytePlus ModelArk - Crie uma no console do ModelArk da região AP ao usar IMAGE_PROVIDER=seedream
Uma ferramenta de IA compatível com MCP: Cursor, Claude Code, Codex ou outras
Conhecimento básico de terminal/linha de comando

Início Rápido

1. Obtenha Sua Chave de API do Gemini

Obtenha sua chave de API no Google AI Studio

Para usar OpenAI em vez disso, obtenha uma chave de API da OpenAI e defina:

IMAGE_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key_here

O modo OpenAI requer verificação da organização. Consulte Usando o provedor OpenAI para detalhes de configuração e diferenças de recursos.

Para usar BytePlus Seedream em vez disso, crie uma chave de API na região AP do ModelArk e defina:

IMAGE_PROVIDER=seedream
ARK_API_KEY=<your-api-key>

Consulte Usando o provedor BytePlus Seedream para detalhes de compatibilidade.

2. Configuração MCP

Para Codex

Adicione a ~/.codex/config.toml:

[mcp_servers.mcp-image]
command = "npx"
args = ["-y", "mcp-image"]

[mcp_servers.mcp-image.env]
GEMINI_API_KEY = "your_gemini_api_key_here"
IMAGE_OUTPUT_DIR = "/absolute/path/to/images"

Para OpenAI GPT Image a partir de um fork local:

[mcp_servers.mcp-image]
command = "node"
args = ["/absolute/path/to/mcp-image/dist/index.js"]

[mcp_servers.mcp-image.env]
IMAGE_PROVIDER = "openai"
OPENAI_API_KEY = "your_openai_api_key_here"
IMAGE_OUTPUT_DIR = "/absolute/path/to/images"

Para Cursor

Adicione às configurações do seu Cursor:

Global (todos os projetos): ~/.cursor/mcp.json
Específico do projeto: .cursor/mcp.json na raiz do seu projeto

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": ["-y", "mcp-image"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Para OpenAI GPT Image a partir de um fork local:

{
  "mcpServers": {
    "mcp-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-image/dist/index.js"],
      "env": {
        "IMAGE_PROVIDER": "openai",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Para Claude Code

Execute no diretório do seu projeto para habilitar para aquele projeto:

cd /path/to/your/project
claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

Ou adicione globalmente para todos os projetos:

claude mcp add mcp-image --scope user --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

Para OpenAI GPT Image a partir de um fork local:

npm install
npm run build
claude mcp add mcp-image --scope user \
  --env IMAGE_PROVIDER=openai \
  --env OPENAI_API_KEY=your-openai-api-key \
  --env IMAGE_OUTPUT_DIR=/absolute/path/to/images \
  -- node /absolute/path/to/mcp-image/dist/index.js

Segurança: Nunca envie chaves de API para o controle de versão. Use configuração específica do ambiente.

Requisitos de caminho:

IMAGE_OUTPUT_DIR deve ser um caminho absoluto (por exemplo, /Users/username/images, não ./images)
O padrão é ./output no diretório de trabalho atual se não for especificado
O diretório será criado automaticamente se não existir

Predefinições de Qualidade

As predefinições equilibram velocidade, qualidade e custo:

Predefinição	Modelo	Melhor para	Velocidade
`fast` (padrão)	Nano Banana 2 (Gemini 3.1 Flash Image)	Iterações rápidas, rascunhos, geração de alto volume	~30–40s
`balanced`	Nano Banana 2 + Thinking	Imagens de produção, boa qualidade com velocidade razoável	Média
`quality`	Nano Banana Pro (Gemini 3 Pro Image)	Entregas finais, fidelidade máxima, visuais críticos	Lenta

Defina o padrão via variável de ambiente IMAGE_QUALITY:

IMAGE_QUALITY=fast       # (default) Fastest generation
IMAGE_QUALITY=balanced   # Enhanced thinking for better quality
IMAGE_QUALITY=quality    # Maximum quality output

Para substituir a predefinição em uma única solicitação, diga ao seu assistente de IA para "gerar em alta qualidade" ou "usar qualidade equilibrada". O assistente passa o parâmetro quality correspondente.

Codex:

[mcp_servers.mcp-image.env]
GEMINI_API_KEY = "your_gemini_api_key_here"
IMAGE_QUALITY = "balanced"

Cursor: Adicione "IMAGE_QUALITY": "balanced" à seção env na sua configuração.

Claude Code:

claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_QUALITY=balanced --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

Pular Aprimoramento de Prompt

Defina SKIP_PROMPT_ENHANCEMENT=true para enviar prompts diretamente ao gerador de imagens. Use isso quando a redação exata do prompt precisar permanecer inalterada.

Configuração do Provedor

Variável	Padrão	Descrição
`IMAGE_PROVIDER`	`gemini`	`gemini`, `openai` ou `seedream`. Usado quando uma solicitação não define `provider`
`GEMINI_API_KEY`	-	Necessário para usar o provedor `gemini`
`OPENAI_API_KEY`	-	Necessário para usar o provedor `openai`
`ARK_API_KEY`	-	Necessário para usar o provedor `seedream`; use uma chave da região AP do ModelArk

Um provider em nível de solicitação tem precedência sobre IMAGE_PROVIDER; se nenhum for definido, gemini é usado. O servidor pode iniciar sem nenhuma chave de API, mas generate_image requer uma chave para o provedor selecionado. Se uma chave estiver ausente, o erro identifica a variável de ambiente a ser configurada.

Usando o provedor BytePlus Seedream

A partir de 29 de julho de 2026, o Seedream 5.0 Pro está disponível apenas no ModelArk AP (ap-southeast-1). Crie uma chave de API no console da região AP do ModelArk.

O mcp-image usa seed-2-0-lite-260428 para aprimoramento de prompt e Seedream 5.0 Pro para geração de imagens. Essas escolhas de modelo são fixas pelo servidor e não são configuráveis através de variáveis de ambiente.

O roteamento de qualidade do Seedream é fixo:

Predefinição pública	Rota Seedream	Otimizador de imagem nativo	`imageSize` suportados	Padrão quando omitido
`fast`	Seedream 5.0 Pro	`fast`	`1K`, `2K`	`1K`
`balanced`	Seedream 5.0 Pro	`standard`	`1K`, `2K`	`1K`
`quality`	Seedream 5.0 Pro	`standard`	`1K`, `2K`	`1K`

Todas as proporções de aspecto suportadas usam o BytePlus Method 1, então as dimensões finais em pixels são selecionadas pelo modelo. O Seedream rejeita imageSize: "4K" e useGoogleSearch: true. As solicitações de imagem têm um tempo limite fixo de 300 segundos. A edição de imagens do Seedream aceita apenas imagens de entrada PNG e JPEG.

Usando o provedor OpenAI

Defina IMAGE_PROVIDER=openai para usar OpenAI tanto para aprimoramento de prompt quanto para geração de imagens. O mcp-image atualmente usa gpt-5.4-nano para aprimoramento de prompt e gpt-image-2 para geração de imagens. Essas escolhas de modelo são fixas pelo servidor e não são configuráveis através de variáveis de ambiente.

A OpenAI pode exigir verificação da organização antes de permitir acesso a gpt-image-2. Se a geração de imagens falhar com um erro de permissão ou verificação 403, verifique as configurações da sua organização: https://platform.openai.com/settings/organization/general

Comportamento do provedor OpenAI:

Suporta geração de texto-para-imagem e imagem-para-imagem.
Suporta aspectRatio, mapeado para o tamanho de imagem OpenAI suportado mais próximo.
Suporta valores imageSize 1K, 2K e 4K.
Mapeia quality como fast -> low, balanced -> medium e quality -> high. Para qualquer coisa além de assuntos simples, balanced ou quality é recomendado.
Não suporta useGoogleSearch; essa opção está disponível apenas com o provedor Gemini.

O aprimoramento de prompt usa uma chamada separada da API OpenAI Responses. Defina SKIP_PROMPT_ENHANCEMENT=true para enviar prompts diretamente ao modelo de imagem.

Exemplos de Uso

Uma vez configurado, descreva a imagem em linguagem natural:

Geração Básica de Imagem

"Generate a serene mountain landscape at sunset with a lake reflection"

O aprimoramento de prompt preenche detalhes relevantes sobre iluminação, materiais, composição e atmosfera.

Edição de Imagem

"Edit this image to make the person face right"
(with inputImagePath: "/path/to/image.jpg")

Opções de Geração

Consistência de Personagem:

"Generate a portrait of a medieval knight, maintaining character consistency for future variations"
(with maintainCharacterConsistency: true)

Alta Resolução 4K com Renderização de Texto:

"Generate a professional product photo of a smartphone with clear text on the screen"
(with imageSize: "4K")

Proporção de Aspecto Personalizada:

"Generate a cinematic landscape of a desert at golden hour"
(with aspectRatio: "21:9")

Referência da API

Ferramenta `generate_image`

O servidor usa um modelo separado para cada um de seus dois estágios:

Otimização de Prompt (Gemini 2.5 Flash por padrão, gpt-5.4-nano via OpenAI Responses no modo OpenAI, ou seed-2-0-lite-260428 via ModelArk Responses no modo Seedream): Refina seu prompt usando a estrutura Assunto–Contexto–Estilo. Pode ser pulado via SKIP_PROMPT_ENHANCEMENT.
Geração de Imagem (Nano Banana 2/Pro por padrão, gpt-image-2 no modo OpenAI, ou Seedream 5.0 Pro no modo Seedream): Cria a imagem final. Os mapeamentos de qualidade específicos do provedor são descritos acima.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	string	✅	Descrição textual ou instrução de edição
`quality`	string	-	Predefinição de qualidade: `fast` (padrão), `balanced`, `quality`. Substitui a variável de ambiente `IMAGE_QUALITY` para esta solicitação
`provider`	string	-	Provedor de imagens: `gemini`, `openai`, `seedream`. Substitui a variável de ambiente `IMAGE_PROVIDER` para esta solicitação; a chave de API do provedor deve estar configurada
`inputImagePath`	string	-	Caminho absoluto para a imagem de entrada para edição imagem-para-imagem
`fileName`	string	-	`.png`, `.jpg` ou `.jpeg` seleciona esse formato de saída para OpenAI/Seedream. Outros sufixos ou ausência de sufixo usam o padrão do provedor, e o nome salvo é corrigido para a extensão real da imagem
`aspectRatio`	string	-	`1:1` (padrão), `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `1:8`, `4:1`, `8:1`
`imageSize`	string	-	`1K`, `2K`, `4K`. Deixe sem especificar para qualidade padrão
`blendImages`	boolean	-	Ativa a mesclagem de múltiplas imagens para combinar vários elementos visuais de forma natural
`maintainCharacterConsistency`	boolean	-	Mantém a consistência da aparência do personagem em diferentes poses e cenas
`useWorldKnowledge`	boolean	-	Usa conhecimento do mundo real para contexto preciso (figuras históricas, pontos de referência, cenários factuais)
`useGoogleSearch`	boolean	-	Ativa a fundamentação do Google Search com Gemini. OpenAI e Seedream rejeitam `true`
`purpose`	string	-	Uso pretendido (ex.: "capa de livro de receitas", "post de mídia social"). Ajuda a adaptar o estilo visual e os detalhes

Resposta

{
  "type": "resource",
  "resource": {
    "uri": "file:///path/to/generated/image.png",
    "name": "image-filename.png",
    "mimeType": "image/png"
  },
  "metadata": {
    "model": "gemini-3.1-flash-image",
    "provider": "gemini",
    "processingTime": 5000,
    "timestamp": "2026-01-01T12:00:00.000Z"
  }
}

Solução de Problemas

Problemas Comuns

"Chave de API não encontrada"

Garanta que GEMINI_API_KEY esteja definida ao usar Gemini, OPENAI_API_KEY esteja definida quando IMAGE_PROVIDER=openai, ou ARK_API_KEY esteja definida quando IMAGE_PROVIDER=seedream
Verifique se a chave de API é válida e possui permissões de geração de imagens

"Arquivo de imagem de entrada não encontrado"

Use caminhos de arquivo absolutos, não caminhos relativos
Garanta que o arquivo exista e seja acessível
Formatos suportados: PNG, JPEG, WebP (máx. 10MB)

"Nenhum dado de imagem encontrado na resposta da API Gemini"

Tente reformular seu prompt com detalhes mais específicos
Garanta que seu prompt seja apropriado para geração de imagens
Verifique se sua chave de API tem cota suficiente

Dicas de Desempenho

No modo Gemini, a predefinição fast normalmente leva ~30–40 segundos, incluindo a otimização do prompt
No modo Gemini, balanced usa raciocínio adicional e quality seleciona Nano Banana Pro
No modo Seedream, use a tabela de rotas acima; todos os níveis usam Pro, com fast selecionando otimização nativa fast e balanced/quality selecionando standard
Alta resolução (2K/4K): O tempo de processamento varia conforme o provedor e a rota
Diga para que serve a imagem; o otimizador fornece os termos fotográficos que isso implica
Detalhes que você especificar são mantidos em vez de reescritos
Considere useWorldKnowledge para assuntos históricos ou factuais
Use imageSize: "4K" quando o provedor selecionado suportar; Seedream aceita 1K e 2K

Notas de Uso

Este servidor MCP usa a API Gemini paga:
- Otimização de prompt: Gemini 2.5 Flash (uso mínimo de tokens)
- Geração de imagens: O modelo depende da predefinição de qualidade
  - fast / balanced: Nano Banana 2 (Gemini 3.1 Flash Image, custo menor)
  - quality: Nano Banana Pro (Gemini 3 Pro Image, custo maior)
- balanced usa tokens de raciocínio adicionais (custo ligeiramente maior que fast)
Verifique preços e limites de taxa atuais em Google AI Studio
Monitore seu uso da API para evitar cobranças inesperadas
A etapa de otimização de prompt adiciona custo mínimo e mantém a intenção da sua solicitação na imagem gerada

Habilidade de Agente Autônomo: Guia de Prompts para Geração de Imagens

Este projeto também inclui uma Agent Skill autônoma (SKILL.md). Use-a para ajudar um assistente de IA a escrever prompts para uma ferramenta que já suporta geração de imagens. A skill é separada do servidor MCP, não o chama e não requer chave de API.

A skill cobre o framework Assunto-Contexto-Estilo, iluminação, texturas, ângulos de câmera, consistência de personagens, composição e edição de imagens. Funciona com Gemini, GPT Image, Flux, Stable Diffusion, Midjourney e outros modelos de imagem.

Instalação

npx mcp-image skills install --path <skills-directory>

A skill será colocada em <skills-directory>/image-generation/SKILL.md. Por exemplo: ~/.cursor/skills (Cursor), ~/.codex/skills (Codex) ou ~/.claude/skills (Claude Code).

Licença

Licença MIT - consulte LICENSE para detalhes.

Precisa de ajuda? Abra uma issue ou consulte a seção de solução de problemas acima.

Image Generator

Documentação

MCP Image Generator 🍌

Como Funciona

Recursos

Pré-requisitos

Início Rápido

1. Obtenha Sua Chave de API do Gemini

2. Configuração MCP

Para Codex

Para Cursor

Para Claude Code

Predefinições de Qualidade

Pular Aprimoramento de Prompt

Configuração do Provedor

Usando o provedor BytePlus Seedream

Usando o provedor OpenAI

Exemplos de Uso

Geração Básica de Imagem

Edição de Imagem

Opções de Geração

Referência da API

Ferramenta generate_image

Parâmetros

Resposta

Solução de Problemas

Problemas Comuns

Dicas de Desempenho

Notas de Uso

Habilidade de Agente Autônomo: Guia de Prompts para Geração de Imagens

Instalação

Licença

Ferramenta `generate_image`