Image Generator

MCP Image Generator 🍌

Gere e edite imagens a partir do Codex, Cursor, Claude Code ou qualquer cliente MCP. O mcp-image adiciona direção visual à sua solicitação antes de enviá-la ao Gemini, OpenAI ou BytePlus Seedream.

Diga a ele qual imagem criar ou o que alterar em uma imagem existente e para que serve. O resultado é salvo em disco e retornado ao seu assistente.

O Que Ele Faz

Antes de gerar uma imagem, o mcp-image reescreve solicitações curtas em prompts mais específicos. Ele mantém o que você pediu e preenche detalhes como composição, iluminação e ângulo de câmera. Quanto mais detalhes você fornecer, menos ele altera.

Você pede:

"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 como é suculento."

O mcp-image envia ao modelo de imagem:

"... um frango inteiro recém-assado descansando sobre uma tábua de corte rústica de madeira temperada. O frango apresenta pele profundamente bronzeada, bolhosa e crocante ... Está parcialmente cortado, com um peito fatiado de forma limpa para revelar carne branca macia e fumegante, brilhando com sucos naturais que se acumulam levemente na tábua ... profundidade de campo rasa com fundo suavemente desfocado."

Gerado com Gemini usando o preset de qualidade padrão fast.

O que foi mantido:

• for a recipe site: um assunto claro, com todo o resto mantido em segundo plano
• actually cooked: douramento bolhoso, escurecimento irregular, vapor subindo e respingos na faca
• partway through being carved: um peito fatiado, com o pedaço cortado ainda apoiado contra a ave
• how juicy it is: sucos acumulados na tábua e profundidade de campo rasa ao redor do corte

Compare a mesma solicitação com o aprimoramento de prompt desativado

Linha de base da mesma solicitação, com o aprimoramento de prompt desativado.

Defina SKIP_PROMPT_ENHANCEMENT=true para enviar o prompt original ao modelo de imagem sem alterações.

Início Rápido

Você precisa do Node.js 22 ou posterior, de um cliente compatível com MCP e de uma chave de API para um provedor de imagens.

1. Obtenha uma chave de API

Todos os três provedores geram e editam imagens. O Gemini é o padrão e requer a menor configuração.

A fundamentação da Pesquisa Google está disponível apenas com o Gemini. A OpenAI pode exigir verificação da organização antes de gerar imagens.

Os exemplos abaixo usam o Gemini. Substitua as configurações do provedor se preferir OpenAI ou Seedream.

2. Configure seu cliente MCP

Codex

Adicione isto 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"

Cursor

Adicione isto a ~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json em um 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"
      }
    }
  }
}

Claude Code

Execute isto no diretório do seu projeto:

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

Adicione --scope user após mcp-image para disponibilizá-lo em todos os projetos.

Nunca envie chaves de API para o controle de versão. Use um IMAGE_OUTPUT_DIR absoluto na configuração do MCP porque o diretório de trabalho do servidor depende do cliente. Se omitido, as imagens são gravadas em ./output relativo a esse diretório de trabalho.

3. Gere uma imagem

Reinicie seu cliente MCP após alterar a configuração e peça ao seu assistente de IA:

Generate a product photo of a ceramic coffee mug on a wooden desk.

O arquivo gerado é salvo no diretório de saída configurado e retornado ao assistente como um recurso MCP.

pnpm install
pnpm run build

node /absolute/path/to/mcp-image/dist/index.js

Mais Exemplos

Editar uma imagem existente

Dê ao assistente um caminho absoluto para a imagem de origem:

Edit /path/to/image.jpg so the person is facing right.

Controlar o resultado

• Generate a high-quality product photo of a smartphone with clear text on the screen.
• Generate a cinematic desert landscape in a 21:9 aspect ratio.
• Keep the knight's appearance consistent with the previous image.

Consulte a referência da ferramenta para ver as opções que seu assistente pode passar explicitamente.

Configuração

Alterar o provedor muda tanto o aprimoramento de prompt quanto a geração de imagens. A forma como você pede uma imagem permanece a mesma.

Qualidade

IMAGE_QUALITY aceita fast (padrão), balanced ou quality. Defina-o no ambiente do servidor MCP:

IMAGE_QUALITY=balanced

Use fast para testar ideias rapidamente, balanced para uso diário e quality para cenas complexas ou imagens em que pequenos detalhes importam. Configurações mais altas podem demorar mais e custar mais; os resultados variam por provedor.

Todos os três provedores suportam esses presets para geração e edição. Você pode substituir o padrão com a opção quality em cada solicitação.

Variáveis de ambiente

Você pode configurar chaves para mais de um provedor e alternar por solicitação. Uma opção provider no nível da solicitação tem precedência sobre IMAGE_PROVIDER.

Referência da Ferramenta

Seu cliente MCP chama esta ferramenta por você. Abra a referência quando precisar verificar uma opção ou limitação do provedor.

Solução de Problemas

Chave de API não encontrada

Verifique se a chave do provedor selecionado está presente no ambiente do servidor MCP:

• Gemini: GEMINI_API_KEY
• OpenAI: OPENAI_API_KEY
• Seedream: ARK_API_KEY

Reinicie o cliente MCP após alterar a configuração.

Arquivo de imagem de entrada não encontrado

Use caminhos absolutos e certifique-se de que o servidor MCP possa ler os arquivos. As imagens de entrada podem ser PNG, JPEG ou WebP e devem ter no máximo 10 MiB cada. A edição do Seedream aceita apenas PNG e JPEG.

Provedor rejeita uma solicitação

Verifique o tamanho solicitado na tabela de provedores. useGoogleSearch funciona apenas com Gemini, e o Seedream não suporta 4K. Para erros de permissão da OpenAI, verifique suas configurações de organização. Para erros de cota ou limite de taxa, verifique a conta do provedor selecionado.

Habilidade de Prompt de Geração de Imagem

Este repositório também inclui uma Agent Skill para assistentes que já têm acesso a uma ferramenta de geração de imagens. Ela ensina a abordagem de escrita de prompts usada pelo mcp-image e funciona independentemente deste servidor.

Instale-a com:

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

Por exemplo, use ~/.codex/skills, ~/.cursor/skills ou ~/.claude/skills como destino.

Licença

Licença MIT. Consulte LICENSE para detalhes.

Precisa de ajuda? Abra uma issue ou consulte Solução de Problemas.