Universal Image MCP

Universal Image MCP - Servidor de Geração de Imagens com IA Multi-Provedor para Claude Desktop e Clientes MCP

Servidor MCP universal para geração de imagens com IA com suporte a AWS Bedrock (Nova Canvas), OpenAI (GPT Image, DALL-E) e Google Gemini (Imagen 4). Gere, transforme e edite imagens usando múltiplos modelos de IA através de uma única interface Model Context Protocol.

O que é o Universal Image MCP?

O Universal Image MCP é um servidor Model Context Protocol (MCP) que fornece acesso unificado a múltiplos provedores de geração de imagens com IA. Seja usando Claude Desktop, Kiro IDE ou qualquer cliente compatível com MCP, este servidor permite gerar e transformar imagens usando:

• AWS Bedrock - Amazon Nova Canvas para geração de imagens de nível empresarial
• OpenAI - GPT Image 1.5, ChatGPT Image, modelos DALL-E
• Google Gemini - Gemini 2.5 Flash Image, Imagen 4, Imagen 4 Ultra

Perfeito para desenvolvedores que criam aplicações de IA, criadores de conteúdo e qualquer pessoa que precise de acesso programático a múltiplas APIs de geração de imagens através de uma única interface.

Exemplos de Saída

Comparação de diagramas de arquitetura gerados por diferentes modelos usando este servidor MCP:

Estilo	Modelo	Saída
Diagrama Técnico	OpenAI gpt-image-1.5
Diagrama Técnico	Google gemini-2.5-flash-image
Diagrama Técnico	AWS amazon.nova-canvas-v1:0
Arte 3D em Clay	Google gemini-2.5-flash-image
Arte 3D em Clay	OpenAI gpt-image-1.5
Arte 3D em Clay	AWS amazon.nova-canvas-v1:0

Ver Prompt Utilizado

Prompt do Diagrama Técnico:

Technical architecture diagram of a Universal Image MCP Server system. The diagram shows:

Top layer: MCP Client (Claude Desktop, Kiro IDE) connecting via Model Context Protocol

Middle layer: Universal Image MCP Server (FastMCP) with three main components:
1. Server Module (server.py) - handles list_models, generate_image, transform_image, prompt_guide tools
2. Provider Module (providers.py) - manages lazy initialization and provider abstraction
3. Configuration - environment variables for ENABLE_AWS, ENABLE_OPENAI, ENABLE_GEMINI

Bottom layer: Three provider boxes side by side:
- AWS Bedrock (boto3) - Amazon Nova Canvas, with AWS credentials and region config
- OpenAI API - GPT Image 1.5, ChatGPT Image Latest, with API key
- Google Gemini API - Gemini 2.5 Flash, Imagen 4, with API key

Data flow arrows showing:
- Client sends tool requests to Server
- Server routes to appropriate Provider based on model_id
- Providers make API calls to their respective services
- Image data flows back through the chain

Clean, professional software architecture diagram style with boxes, arrows, and labels. Use blue and gray color scheme. Modern technical documentation aesthetic. Isometric or layered view showing clear separation of concerns.

Prompt da Arte 3D em Clay:

Same technical architecture content as above, but rendered in:

3D clay art style with soft rounded shapes, pastel colors, cute minimalist aesthetic, soft studio lighting, clean composition with depth and shadows.

Nota: As versões de Arte 3D em Clay usaram s3tablearch.png como imagem de referência para orientação de estilo.

Principais Recursos

• 🔄 Suporte Multi-Provedor - Alterne entre AWS Bedrock, OpenAI e Google Gemini sem interrupções
• 🚀 Descoberta Dinâmica de Modelos - Busca automaticamente os modelos mais recentes disponíveis em cada API de provedor
• ⚡ Inicialização Preguiçosa - Clientes de provedores carregam apenas quando necessário para desempenho ideal
• 🎨 Suporte a Imagem de Referência - Gere novas imagens com base em estilos de imagens existentes
• 📐 Dimensões Configuráveis - Largura/altura personalizadas para modelos de IA suportados
• 📚 Guia de Prompt Integrado - Melhores práticas para escrever prompts eficazes de geração de imagens
• 🔌 Protocolo MCP - Funciona com Claude Desktop, Kiro IDE e todos os clientes compatíveis com MCP
• 🐍 Python 3.11+ - Python moderno com dicas de tipo e suporte assíncrono

Instalação de Início Rápido

Instale via pip:

pip install universal-image-mcp

Ou use com uvx (recomendado para servidores MCP):

uvx universal-image-mcp@latest

Configuração do Servidor MCP

Para Claude Desktop

Adicione ao seu arquivo de configuração MCP do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "universal-image-mcp": {
      "command": "uvx",
      "args": ["universal-image-mcp@latest"],
      "env": {
        "ENABLE_AWS": "true",
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1",
        
        "ENABLE_OPENAI": "true",
        "OPENAI_API_KEY": "sk-...",
        
        "ENABLE_GEMINI": "true",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}

Para Kiro IDE

Adicione ao ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "universal-image-mcp": {
      "command": "uvx",
      "args": ["universal-image-mcp@latest"],
      "env": {
        "ENABLE_AWS": "true",
        "ENABLE_OPENAI": "true",
        "OPENAI_API_KEY": "sk-...",
        "ENABLE_GEMINI": "true",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}

Obtendo Chaves de API e Credenciais

Antes de usar este servidor MCP, você precisará obter credenciais para os provedores que deseja usar.

Configuração do AWS Bedrock

O AWS Bedrock usa suas credenciais AWS locais. Você tem várias opções:

1. Configuração da AWS CLI (Recomendado)

   • Instale a AWS CLI
   • Execute aws configure e forneça sua chave de acesso, chave secreta e região
   • Guia oficial: Configuração da AWS CLI

2. Arquivo de Credenciais AWS

   • Crie ~/.aws/credentials com suas chaves de acesso
   • Crie ~/.aws/config com suas configurações de região
   • Guia oficial: Arquivos de Configuração e Credenciais Compartilhados

3. Variáveis de Ambiente

   • Defina AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_REGION
   • Guia oficial: Autenticação da AWS CLI

Obtendo Chaves de Acesso AWS:

• Entre no Console AWS
• Navegue até IAM → Usuários → Seu Usuário → Credenciais de Segurança
• Crie uma nova chave de acesso em "Chaves de acesso"
• Certifique-se de que seu usuário IAM tenha permissões para Bedrock (por exemplo, política AmazonBedrockFullAccess)

Chave de API OpenAI

1. Crie uma Conta OpenAI

   • Visite Plataforma OpenAI
   • Cadastre-se ou faça login na sua conta

2. Gere a Chave de API

   • Vá para a página de Chaves de API
   • Clique em "Criar nova chave secreta"
   • Dê um nome descritivo (opcional)
   • Copie a chave imediatamente (você não poderá vê-la novamente)

3. Adicione Informações de Cobrança

   • A OpenAI exige informações de pagamento para usar a API
   • Navegue até Cobrança para adicionar detalhes de pagamento

Documentação Oficial: Guia de Início Rápido OpenAI

Chave de API Google Gemini

1. Obtenha uma Chave de API Gemini

   • Visite Google AI Studio
   • Entre com sua conta Google
   • Clique em "Obter Chave de API" ou "Criar Chave de API"
   • Crie um novo projeto ou selecione um existente
   • Copie sua chave de API

2. Alternativa: Chave de API Google Cloud

   • Para uso em produção, você pode usar Vertex AI no Google Cloud
   • Isso fornece mais recursos empresariais e controles de cobrança

Documentação Oficial: Início Rápido da API Gemini

Variáveis de Ambiente

Variável	Obrigatória	Descrição
ENABLE_AWS	Não	Habilita o provedor AWS Bedrock (true/false, padrão: false)
AWS_PROFILE	Não	Nome do perfil AWS (padrão, SSO ou perfil nomeado)
AWS_REGION	Não	Região AWS (padrão: us-east-1)
ENABLE_OPENAI	Não	Habilita o provedor OpenAI (true/false, padrão: false)
OPENAI_API_KEY	Se OpenAI habilitado	Chave de API OpenAI de platform.openai.com
ENABLE_GEMINI	Não	Habilita o provedor Google Gemini (true/false, padrão: false)
GEMINI_API_KEY	Se Gemini habilitado	Chave de API Google Gemini de Google AI Studio

Referência da API - Ferramentas MCP

list_models()

Lista todos os modelos de geração de imagens com IA disponíveis dos provedores habilitados. Os modelos são buscados dinamicamente da API de cada provedor, com modelos obsoletos filtrados automaticamente.

Retorna: Lista formatada de IDs de modelos compatíveis com generate_image() e transform_image()

Exemplos de modelos:

• AWS: amazon.nova-canvas-v1:0
• OpenAI: gpt-image-1.5, chatgpt-image-latest
• Gemini: models/gemini-2.5-flash-image, models/imagen-4.0-generate-001

generate_image(prompt, model_id, output_path, reference_image?, width?, height?)

Gera imagens com IA a partir de prompts de texto usando qualquer modelo suportado.

Parâmetro	Obrigatório	Padrão	Descrição
prompt	Sim	-	Descrição textual detalhada da imagem. Seja específico sobre assunto, estilo, iluminação, cores, composição e clima.
model_id	Sim	-	ID do modelo de list_models(). Exemplos: amazon.nova-canvas-v1:0, gpt-image-1.5, models/gemini-2.5-flash-image
output_path	Sim	-	Caminho do arquivo para salvar a imagem gerada. Diretórios pais são criados automaticamente.
reference_image	Não	None	Caminho para imagem de referência para orientação de estilo/conteúdo
width	Não	1024	Largura da imagem em pixels. Nota: Alguns modelos suportam apenas tamanhos específicos.
height	Não	1024	Altura da imagem em pixels. Nota: Alguns modelos suportam apenas tamanhos específicos.

### transform_image(image_path, prompt, model_id, output_path)

Transforme e edite imagens existentes usando modificações alimentadas por IA com base em prompts de texto.

Parâmetro	Obrigatório	Descrição
image_path	Sim	Caminho para a imagem de origem a ser transformada (PNG, JPEG, etc.)
prompt	Sim	Instruções de transformação por IA (ex.: "Deixe em preto e branco", "Adicione um arco-íris", "Converta para estilo aquarela")
model_id	Sim	ID do modelo de list_models()
output_path	Sim	Caminho do arquivo para salvar a imagem transformada

Casos de uso: Edição de imagens, transferência de estilo, manipulação de fotos com IA, transformações artísticas

prompt_guide()

Obtenha as melhores práticas de engenharia de prompts de IA para geração de imagens. Retorna diretrizes abrangentes que cobrem:

• Estrutura do prompt (Assunto + Detalhes + Estilo + Iluminação + Humor + Composição)
• Descrições específicas versus genéricas
• Palavras-chave de estilo, iluminação e humor
• Exemplos de prompts para diferentes casos de uso

Modelos de Imagem de IA Suportados

Todos os modelos são descobertos dinamicamente. Use list_models() para ver as opções atuais.

Modelos AWS Bedrock

• Amazon Nova Canvas (amazon.nova-canvas-v1:0) - Geração de imagens de nível empresarial com suporte a entrada de texto e imagem

Modelos OpenAI

• GPT Image 1.5 (gpt-image-1.5) - Modelo mais recente de geração de imagens da OpenAI
• ChatGPT Image Latest (chatgpt-image-latest) - Geração de imagens integrada ao ChatGPT

Modelos Google Gemini

• Gemini 2.5 Flash Image (models/gemini-2.5-flash-image) - Geração de imagens rápida e eficiente
• Gemini 3 Pro Image (models/gemini-3-pro-image-preview) - Capacidades avançadas de geração de imagens
• Imagen 4 (models/imagen-4.0-generate-001) - Modelo de imagem de última geração do Google
• Imagen 4 Ultra (models/imagen-4.0-ultra-generate-001) - Modelo Imagen de maior qualidade
• Imagen 4 Fast (models/imagen-4.0-fast-generate-001) - Otimizado para velocidade

Casos de Uso

• Desenvolvimento de Aplicações de IA - Integre múltiplos provedores de geração de imagens aos seus aplicativos
• Criação de Conteúdo - Gere materiais de marketing, conteúdo para redes sociais, ilustrações
• Prototipagem e Design - Visualize rapidamente conceitos e ideias de design
• Automação de Edição de Imagens - Processe e transforme imagens em lote com IA
• Pesquisa e Experimentação - Compare resultados entre diferentes modelos de IA
• Fluxos de Trabalho no Claude Desktop - Enriqueça conversas no Claude com geração de imagens
• Ferramentas para Desenvolvedores - Crie ferramentas e extensões compatíveis com MCP

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, abra uma issue primeiro para discutir o que você gostaria de alterar.

Projetos Relacionados

• Model Context Protocol - Documentação oficial do MCP
• Claude Desktop - Assistente de IA com suporte a MCP
• FastMCP - Framework Python para construir servidores MCP

Palavras-chave

mcp-server image-generation ai-images aws-bedrock openai google-gemini claude-desktop imagen nova-canvas python fastmcp model-context-protocol ai-art text-to-image image-transformation

Licença

MIT