AI Image MCP Server

Servidor MCP de Imágenes IA

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que proporciona capacidades tanto de análisis de imágenes impulsado por IA como de generación de imágenes IA utilizando la API de Visión de OpenAI y los modelos de generación de imágenes.

Requisitos del Sistema

Probado en:

• macOS 14.3.0 (Darwin 23.3.0, ARM64)
• Python 3.13.0
• uv 0.7.13
• Acceso a la API de OpenAI

Características

🔍 Análisis y Descripción de Imágenes

• Análisis Inteligente de Imágenes: Analiza imágenes utilizando el modelo de Visión GPT-4O de OpenAI
• Análisis Dirigido: Analiza aspectos específicos (objetos, texto, colores, composición, emociones)
• Comparaciones de Imágenes: Compara dos imágenes y resalta similitudes/diferencias
• Extracción de Metadatos: Obtén información técnica sobre archivos de imagen
• Caché Inteligente: Almacena en caché los resultados del análisis para evitar llamadas repetidas a la API
• Múltiples Formatos: Soporte para formatos PNG, JPEG, GIF y WebP

🎨 Generación y Edición de Imágenes

• Generación de Texto a Imagen: Crea imágenes a partir de indicaciones de texto utilizando DALL-E 2, DALL-E 3 o GPT-Image-1
• Edición de Imágenes: Edita imágenes existentes con indicaciones de texto utilizando GPT-Image-1 o DALL-E 2
• Variaciones de Imágenes: Crea variaciones de imágenes existentes utilizando DALL-E 2
• Salida Flexible: Guarda imágenes generadas localmente con nombres y directorios personalizados
• Soporte de Modelos: Soporte completo para todos los modelos de generación de imágenes de OpenAI con sus características específicas

Herramientas MCP

1. describe_image(image_path, prompt) - Obtén descripciones detalladas de imágenes
2. analyze_image_content(image_path, analysis_type) - Analiza aspectos específicos
3. compare_images(image1_path, image2_path, comparison_focus) - Compara dos imágenes
4. get_image_metadata(image_path) - Extrae metadatos técnicos
5. get_cache_info() - Ver estadísticas de caché
6. clear_image_cache() - Limpia resultados almacenados en caché

Instalación

1. Instala las dependencias:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv add mcp[cli] openai pillow requests

2. Configura tu clave de API de OpenAI:

export OPENAI_API_KEY="your-api-key-here"

3. Ejecuta el servidor:

uv run main.py

Ejecutando el Servidor

uv run main.py

Integración 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

Configura MCP en la configuración de 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álisis

• general: Descripción general de la imagen
• objects: Detección e identificación de objetos
• text: Extracción de texto y OCR
• colors: Análisis de colores y paleta
• composition: Composición visual y diseño
• emotions: Contenido emocional y estado de ánimo

Estructura del Proyecto

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

Caché

• Detección automática de cambios en archivos mediante hashes SHA-256
• Caducidad de caché de 30 días
• Entradas de caché separadas para diferentes indicaciones/tipos de análisis
• Mejoras significativas de rendimiento (1000x+ más rápido que las llamadas a la API)

Herramientas Disponibles

Herramientas de Análisis de Imágenes

describe_image

Analiza una imagen y proporciona una descripción detallada.

• Parámetros:
  • image_path (str): Ruta al archivo de imagen
  • prompt (str, opcional): Indicación de análisis personalizada
• Soporta: PNG, JPEG, GIF, WebP
• Características: Caché, validación de archivos, manejo integral de errores

analyze_image_content

Realiza análisis dirigido de aspectos específicos de la imagen.

• Parámetros:
  • image_path (str): Ruta al archivo de imagen
  • analysis_type (str): Tipo de análisis - "general", "objects", "text", "colors", "composition", "emotions"
• Características: Indicaciones especializadas para diferentes tipos de análisis

compare_images

Compara dos imágenes y resalta similitudes y diferencias.

• Parámetros:
  • image1_path (str): Ruta a la primera imagen
  • image2_path (str): Ruta a la segunda imagen
  • comparison_focus (str): En qué enfocarse en la comparación

get_image_metadata

Obtén metadatos técnicos sobre un archivo de imagen.

• Devuelve: Tamaño del archivo, dimensiones, formato, modo de color, relación de aspecto, etc.

Herramientas de Generación de Imágenes

generate_image

Genera imágenes a partir de indicaciones de texto utilizando los modelos de generación de imágenes de OpenAI.

• Parámetros:
  • prompt (str): Descripción de texto de la imagen deseada
  • model (str): "dall-e-2", "dall-e-3" o "gpt-image-1" (predeterminado: dall-e-3)
  • size (str, opcional): Dimensiones de la imagen (varía según el modelo)
  • quality (str, opcional): Configuración de calidad (varía según el modelo)
  • style (str, opcional): "vivid" o "natural" (solo DALL-E 3)
  • n (int, opcional): Número de imágenes (1-10, DALL-E 3 solo soporta 1)
  • output_dir (str): Directorio para guardar imágenes (predeterminado: "./generated_images")
  • filename_prefix (str): Prefijo para nombres de archivo (predeterminado: "generated")

Características Específicas del Modelo:

• DALL-E 2: Generación básica, tamaños: 256x256, 512x512, 1024x1024
• DALL-E 3: Alta calidad, estilos (vivid/natural), tamaños: 1024x1024, 1792x1024, 1024x1792
• GPT-Image-1: Características avanzadas, soporte de transparencia, control de compresión

edit_image

Edita imágenes existentes utilizando indicaciones de texto.

• Parámetros:
  • image_path (str): Ruta a la imagen a editar
  • prompt (str): Descripción de la edición deseada
  • mask_path (str, opcional): Ruta a la imagen de máscara (PNG con áreas de edición transparentes)
  • model (str): "gpt-image-1" o "dall-e-2" (predeterminado: gpt-image-1)
  • size, quality, n: Opciones específicas del modelo
  • output_dir, filename_prefix: Configuración de salida

Modelos Soportados: GPT-Image-1 (hasta 16 imágenes, 50MB cada una) y DALL-E 2 (1 PNG cuadrado, máximo 4MB)

create_image_variations

Crea variaciones de imágenes existentes utilizando DALL-E 2.

• Parámetros:
  • image_path (str): Ruta a la imagen fuente (debe ser PNG cuadrado, <4MB)
  • n (int): Número de variaciones (1-10, predeterminado: 2)
  • size (str): Tamaño de variación - "256x256", "512x512", "1024x1024"
  • output_dir, filename_prefix: Configuración de salida

list_generated_images

Lista todas las imágenes generadas en un directorio con metadatos.

• Parámetros:
  • directory (str): Directorio a escanear (predeterminado: "./generated_images")
• Devuelve: Listado de archivos con tamaños, dimensiones, fechas de modificación

Herramientas de Gestión de Caché

get_cache_info

Obtén información sobre la caché de análisis (número de archivos, tamaño, ubicación).

clear_image_cache

Limpia todos los resultados de análisis almacenados en caché.

Comparación de Modelos

Característica	DALL-E 2	DALL-E 3	GPT-Image-1
Generación	✅ Básica	✅ Alta Calidad	✅ Avanzada
Edición	✅ Limitada	❌	✅ Avanzada
Variaciones	✅	❌	❌
Máx. Imágenes	10	1	10
Tamaños	256x256, 512x512, 1024x1024	1024x1024, 1792x1024, 1024x1792	1024x1024, 1536x1024, 1024x1536
Estilos	❌	vivid, natural	❌
Calidad	standard	standard, hd	auto, high, medium, low
Transparencia	❌	❌	✅
Máx. Indicación	1000 caracteres	4000 caracteres	32000 caracteres

Ejemplos de Uso

Generar una Imagen 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 una Imagen 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"
)

Crear Variaciones de Imágenes

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

Analizar Imágenes Generadas

# 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"
)

Organización de Archivos

Las imágenes generadas se organizan automáticamente en directorios separados:

• ./generated_images/ - Generaciones de texto a imagen
• ./edited_images/ - Ediciones de imágenes
• ./image_variations/ - Variaciones de imágenes

Los archivos se nombran con marcas de tiempo para evitar conflictos:

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

Manejo de Errores

El servidor incluye manejo integral de errores para:

• Formatos de imagen y rutas de archivo inválidos
• Validación de parámetros específicos del modelo
• Límites de tamaño de archivo y dimensiones
• Cuotas de API y límites de velocidad
• Problemas de conectividad de red
• Indicaciones y parámetros malformados

Sistema de Caché

Las herramientas de análisis utilizan un sistema de caché inteligente:

• Detección de Cambios en Archivos: Utiliza hashes SHA-256 para detectar cambios en archivos
• Caducidad de 30 Días: Caduca automáticamente entradas de caché antiguas
• Operación Segura: Los fallos de caché no afectan la funcionalidad principal
• Almacenamiento Eficiente: Utiliza hashes MD5 para la generación segura de claves de caché

Requisitos

• Python 3.13+
• Clave de API de OpenAI con acceso a la API de Visión y Generación de Imágenes
• Paquetes requeridos: mcp[cli]>=1.9.4, openai>=1.90.0, pillow>=11.2.1, requests>=2.32.4

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.