OpenAI GPT Image

Gere e edite imagens usando as APIs de geração e edição de imagens GPT-4o da OpenAI com controle avançado de prompts.

GitHub
1
Experimente este MCPPatrocinado

Documentação

openai-gpt-image-mcp

NPM version MCP SDK OpenAI SDK License GitHub stars

Um servidor de ferramentas Model Context Protocol (MCP) para as APIs de geração e edição de imagens GPT-4o/gpt-image-1 da OpenAI.

  • Gere imagens a partir de prompts de texto usando os modelos mais recentes da OpenAI.
  • Edite imagens (inpainting, outpainting, composição) com controle avançado de prompts.
  • Suporta: Claude Desktop, Cursor, VSCode, Windsurf e qualquer cliente compatível com MCP.

✨ Recursos

  • create-image: Gere imagens a partir de um prompt, com opções avançadas (tamanho, qualidade, fundo, etc).
  • edit-image: Edite ou estenda imagens usando um prompt e máscara opcional, suportando tanto caminhos de arquivo quanto entrada base64.
  • Suporte a Proporção de Tela: Use proporções comuns como 16:9, 9:16, 1:1, paisagem, retrato, etc., que são mapeadas automaticamente para tamanhos suportados.
  • Saída de arquivo: Salve imagens geradas diretamente no disco ou receba como base64.
  • Nomes de Arquivo Gerados por IA: A IA pode fornecer nomes de arquivo descritivos como "gato-jogando-futebol.jpg" com base no conteúdo da imagem.

🚀 Instalação

Configuração Rápida com NPX (Recomendado)

Não é necessário instalar! Use diretamente com npx:

{
  "mcpServers": {
    "openai-gpt-image": {
      "command": "npx",
      "args": ["openai-gpt-image-mcp-199bio"],
      "env": { 
        "OPENAI_API_KEY": "sk-..." 
      }
    }
  }
}

Instalação Manual

npm install -g openai-gpt-image-mcp-199bio

Ou compile a partir do código-fonte:

git clone https://github.com/199-biotechnologies/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build

🔑 Configuração

A configuração mostrada acima na seção de Configuração Rápida funciona para todos os clientes compatíveis com MCP:

  • Claude Desktop
  • VSCode
  • Cursor
  • Windsurf

Basta adicionar a configuração ao arquivo de configuração do seu cliente MCP com sua chave de API da OpenAI.

⚡ Avançado

Suporte a Proporção de Tela

As ferramentas agora suportam proporções de tela comuns que são mapeadas automaticamente para os tamanhos suportados pela OpenAI:

  • Quadrado: 1:1, square, 4:3, 3:4 → 1024x1024
  • Paisagem: 16:9, landscape, 3:2 → 1536x1024
  • Retrato: 9:16, portrait, 2:3 → 1024x1536
  • Automático: auto → Deixe a OpenAI escolher o melhor tamanho

Exemplo: Em vez de especificar size: "1536x1024", você pode usar size: "16:9" ou size: "landscape".

Outras Opções

  • Para create-image, defina n para gerar até 10 imagens de uma vez.
  • Para edit-image, forneça uma imagem de máscara (caminho de arquivo ou base64) para controlar onde as edições são aplicadas.
  • Veja src/index.ts para todas as opções.

🧑‍💻 Desenvolvimento

  • Código-fonte TypeScript: src/index.ts
  • Compilar: yarn build
  • Executar: node dist/index.js

📝 Licença

MIT

🩺 Solução de Problemas

  • Certifique-se de que sua OPENAI_API_KEY é válida e tem acesso à API de imagens.
  • Você deve ter uma organização OpenAI verificada. Após a verificação, pode levar de 15 a 20 minutos para o acesso à API de imagens ser ativado.
  • Os caminhos de arquivo devem ser absolutos.
    • Unix/macOS/Linux: Começando com / (por exemplo, /path/to/image.png)
    • Windows: Letra da unidade seguida por : (por exemplo, C:/path/to/image.png ou C:\path\to\image.png)
  • Para saída de arquivo, certifique-se de que o diretório tenha permissão de escrita.
  • Se você vir erros sobre tipos de arquivo, verifique as extensões e formatos dos seus arquivos de imagem.

⚠️ Limitações e Manipulação de Arquivos Grandes

  • Limite de Payload de 1MB: Clientes MCP (incluindo Claude Desktop) têm um limite rígido de 1MB para respostas de ferramentas. Imagens grandes (especialmente de alta resolução ou múltiplas imagens) podem facilmente exceder esse limite se retornadas como base64.
  • Alternância Automática para Saída de Arquivo: Se o tamanho total da imagem exceder 1MB, a ferramenta salvará automaticamente as imagens no disco e retornará o(s) caminho(s) do(s) arquivo(s) em vez de base64. Isso garante compatibilidade e evita erros como result exceeds maximum length of 1048576.
  • Local Padrão de Arquivo:
    • macOS/Linux: As imagens são salvas em ~/Pictures/gpt-image/ por padrão
    • Alternativa: Se o diretório padrão não puder ser criado, as imagens serão salvas em /tmp (ou no diretório definido pela variável de ambiente MCP_HF_WORK_DIR)
    • Caminho Personalizado: Você sempre pode especificar um caminho file_output personalizado para substituir o padrão
  • Nomes de Arquivo Gerados por IA:
    • A IA pode fornecer nomes de arquivo descritivos através do parâmetro filename (por exemplo, "gato-jogando-futebol", "pôr-do-sol-sobre-montanhas")
    • Os nomes de arquivo são sanitizados automaticamente para prevenir problemas de segurança
    • Se múltiplas imagens forem geradas, um índice é anexado (por exemplo, "gato-jogando-futebol_1.jpg", "gato-jogando-futebol_2.jpg")
  • Variável de Ambiente:
    • MCP_HF_WORK_DIR: Defina isso para controlar o diretório alternativo para imagens grandes e saídas de arquivo. Exemplo: export MCP_HF_WORK_DIR=/your/desired/dir
  • Melhor Prática: Para imagens grandes ou de produção, sempre use saída de arquivo e certifique-se de que seu cliente está configurado para lidar com caminhos de arquivo.

📚 Referências

🙏 Créditos