AI Image MCP Server

Análise de imagens com inteligência artificial usando a API Vision da OpenAI.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Imagens com IA

Um servidor abrangente de Model Context Protocol (MCP) que fornece tanto análise de imagens com IA quanto geração de imagens com IA usando a API de Visão da OpenAI e modelos de geração de imagens.

Requisitos do Sistema

Testado em:

  • macOS 14.3.0 (Darwin 23.3.0, ARM64)
  • Python 3.13.0
  • uv 0.7.13
  • Acesso à API da OpenAI

Recursos

🔍 Análise e Descrição de Imagens

  • Análise Inteligente de Imagens: Analise imagens usando o modelo de Visão GPT-4O da OpenAI
  • Análise Direcionada: Analise aspectos específicos (objetos, texto, cores, composição, emoções)
  • Comparação de Imagens: Compare duas imagens e destaque semelhanças/diferenças
  • Extração de Metadados: Obtenha informações técnicas sobre arquivos de imagem
  • Cache Inteligente: Armazene resultados de análise em cache para evitar chamadas repetidas à API
  • Múltiplos Formatos: Suporte para formatos PNG, JPEG, GIF e WebP

🎨 Geração e Edição de Imagens

  • Geração de Texto para Imagem: Crie imagens a partir de prompts de texto usando DALL-E 2, DALL-E 3 ou GPT-Image-1
  • Edição de Imagens: Edite imagens existentes com prompts de texto usando GPT-Image-1 ou DALL-E 2
  • Variações de Imagens: Crie variações de imagens existentes usando DALL-E 2
  • Saída Flexível: Salve imagens geradas localmente com nomes e diretórios personalizados
  • Suporte a Modelos: Suporte completo para todos os modelos de geração de imagens da OpenAI com seus recursos específicos

Ferramentas MCP

  1. describe_image(image_path, prompt) - Obtenha descrições detalhadas de imagens
  2. analyze_image_content(image_path, analysis_type) - Analise aspectos específicos
  3. compare_images(image1_path, image2_path, comparison_focus) - Compare duas imagens
  4. get_image_metadata(image_path) - Extraia metadados técnicos
  5. get_cache_info() - Veja estatísticas do cache
  6. clear_image_cache() - Limpe resultados em cache

Instalação

  1. Instale as dependências:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv add mcp[cli] openai pillow requests
  1. Defina sua chave de API da OpenAI:
export OPENAI_API_KEY="your-api-key-here"
  1. Execute o servidor:
uv run main.py

Executando o Servidor

uv run main.py

Integração MCP

Claude Desktop

{
  "mcpServers": {
    "ai-image-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ai-image-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Configure o MCP nas configurações do Cursor:

{
  "servers": {
    "ai-image-mcp": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/absolute/path/to/ai-image-mcp",
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tipos de Análise

  • general: Descrição geral da imagem
  • objects: Detecção e identificação de objetos
  • text: Extração de texto e OCR
  • colors: Análise de cores e paleta
  • composition: Composição visual e layout
  • emotions: Conteúdo emocional e humor

Estrutura do Projeto

ai-image-mcp/
├── test_data/      # Sample images (gitignored)
├── tools/          # MCP tool definitions
├── utils/          # Utilities (caching, OpenAI client)
├── main.py         # Server entry point
└── server.py       # MCP server instance

Cache

  • Detecção automática de alterações em arquivos via hashes SHA-256
  • Expiração do cache em 30 dias
  • Entradas de cache separadas para diferentes prompts/tipos de análise
  • Melhorias significativas de desempenho (1000x+ mais rápido que chamadas à API)

Ferramentas Disponíveis

Ferramentas de Análise de Imagens

describe_image

Analise uma imagem e forneça uma descrição detalhada.

  • Parâmetros:
    • image_path (str): Caminho para o arquivo de imagem
    • prompt (str, opcional): Prompt de análise personalizado
  • Suporta: PNG, JPEG, GIF, WebP
  • Recursos: Cache, validação de arquivos, tratamento abrangente de erros

analyze_image_content

Realize análise direcionada de aspectos específicos da imagem.

  • Parâmetros:
    • image_path (str): Caminho para o arquivo de imagem
    • analysis_type (str): Tipo de análise - "general", "objects", "text", "colors", "composition", "emotions"
  • Recursos: Prompts especializados para diferentes tipos de análise

compare_images

Compare duas imagens e destaque semelhanças e diferenças.

  • Parâmetros:
    • image1_path (str): Caminho para a primeira imagem
    • image2_path (str): Caminho para a segunda imagem
    • comparison_focus (str): No que focar na comparação

get_image_metadata

Obtenha metadados técnicos sobre um arquivo de imagem.

  • Retorna: Tamanho do arquivo, dimensões, formato, modo de cor, proporção, etc.

Ferramentas de Geração de Imagens

generate_image

Gere imagens a partir de prompts de texto usando os modelos de geração de imagens da OpenAI.

  • Parâmetros:
    • prompt (str): Descrição textual da imagem desejada
    • model (str): "dall-e-2", "dall-e-3" ou "gpt-image-1" (padrão: dall-e-3)
    • size (str, opcional): Dimensões da imagem (varia por modelo)
    • quality (str, opcional): Configuração de qualidade (varia por modelo)
    • style (str, opcional): "vivid" ou "natural" (apenas DALL-E 3)
    • n (int, opcional): Número de imagens (1-10, DALL-E 3 suporta apenas 1)
    • output_dir (str): Diretório para salvar imagens (padrão: "./generated_images")
    • filename_prefix (str): Prefixo para nomes de arquivo (padrão: "generated")

Recursos Específicos por Modelo:

  • DALL-E 2: Geração básica, tamanhos: 256x256, 512x512, 1024x1024
  • DALL-E 3: Alta qualidade, estilos (vivid/natural), tamanhos: 1024x1024, 1792x1024, 1024x1792
  • GPT-Image-1: Recursos avançados, suporte a transparência, controle de compressão

edit_image

Edite imagens existentes usando prompts de texto.

  • Parâmetros:
    • image_path (str): Caminho para a imagem a ser editada
    • prompt (str): Descrição da edição desejada
    • mask_path (str, opcional): Caminho para imagem de máscara (PNG com áreas de edição transparentes)
    • model (str): "gpt-image-1" ou "dall-e-2" (padrão: gpt-image-1)
    • size, quality, n: Opções específicas do modelo
    • output_dir, filename_prefix: Configuração de saída

Modelos Suportados: GPT-Image-1 (até 16 imagens, 50MB cada) e DALL-E 2 (1 PNG quadrado, máx. 4MB)

create_image_variations

Crie variações de imagens existentes usando DALL-E 2.

  • Parâmetros:
    • image_path (str): Caminho para a imagem de origem (deve ser PNG quadrado, <4MB)
    • n (int): Número de variações (1-10, padrão: 2)
    • size (str): Tamanho da variação - "256x256", "512x512", "1024x1024"
    • output_dir, filename_prefix: Configuração de saída

list_generated_images

Liste todas as imagens geradas em um diretório com metadados.

  • Parâmetros:
    • directory (str): Diretório para escanear (padrão: "./generated_images")
  • Retorna: Listagem de arquivos com tamanhos, dimensões, datas de modificação

Ferramentas de Gerenciamento de Cache

get_cache_info

Obtenha informações sobre o cache de análise (contagem de arquivos, tamanho, localização).

clear_image_cache

Limpe todos os resultados de análise em cache.

Comparação de Modelos

RecursoDALL-E 2DALL-E 3GPT-Image-1
Geração✅ Básica✅ Alta Qualidade✅ Avançada
Edição✅ Limitada❌✅ Avançada
Variações✅❌❌
Máx. Imagens10110
Tamanhos256x256, 512x512, 1024x10241024x1024, 1792x1024, 1024x17921024x1024, 1536x1024, 1024x1536
Estilos❌vivid, natural❌
Qualidadestandardstandard, hdauto, high, medium, low
Transparência❌❌✅
Máx. Prompt1000 caracteres4000 caracteres32000 caracteres

Exemplos de Uso

Gerar uma Imagem Básica

# Generate an image with DALL-E 3
generate_image(
    prompt="A serene mountain landscape at sunset with a crystal clear lake",
    model="dall-e-3",
    size="1792x1024",
    quality="hd",
    style="natural"
)

Editar uma Imagem Existente

# Add elements to an image
edit_image(
    image_path="./photos/room.png",
    prompt="Add a beautiful bookshelf filled with colorful books to the left wall",
    model="gpt-image-1",
    quality="high"
)

Criar Variações de Imagem

# Create variations of a logo
create_image_variations(
    image_path="./logos/logo.png",
    n=5,
    size="1024x1024"
)

Analisar Imagens Geradas

# Analyze a generated image
describe_image(
    image_path="./generated_images/generated_1234567890_1.png",
    prompt="Describe the artistic style and composition of this generated image"
)

Organização de Arquivos

As imagens geradas são organizadas automaticamente em diretórios separados:

  • ./generated_images/ - Gerações de texto para imagem
  • ./edited_images/ - Edições de imagem
  • ./image_variations/ - Variações de imagem

Os arquivos são nomeados com timestamps para evitar conflitos:

  • generated_1234567890_1.png
  • edited_1234567890_1.png
  • variation_1234567890_1.png

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

  • Formatos de imagem inválidos e caminhos de arquivo incorretos
  • Validação de parâmetros específicos do modelo
  • Limites de tamanho e dimensão de arquivos
  • Cotas de API e limitação de taxa
  • Problemas de conectividade de rede
  • Prompts e parâmetros malformados

Sistema de Cache

As ferramentas de análise usam um sistema de cache inteligente:

  • Detecção de Alterações em Arquivos: Usa hashes SHA-256 para detectar alterações em arquivos
  • Expiração em 30 Dias: Expira automaticamente entradas antigas do cache
  • Operação Segura: Falhas no cache não afetam a funcionalidade principal
  • Armazenamento Eficiente: Usa hashes MD5 para geração segura de chaves de cache

Requisitos

  • Python 3.13+
  • Chave de API da OpenAI com acesso à API de Visão e Geração de Imagens
  • Pacotes necessários: mcp[cli]>=1.9.4, openai>=1.90.0, pillow>=11.2.1, requests>=2.32.4

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.