Servidor de reconocimiento de imágenes MCP

Un servidor MCP que ofrece capacidades de reconocimiento de imágenes mediante las API de visión de IA de Anthropic, OpenAI y Cloudflare Workers. Versión 1.2.1.

Autores

Originalmente este proyecto fue creado por @mario-andreschak . ¡Gracias!
Actualmente lo mantiene @zudsniper .

Related MCP server: Textin MCP Server

Características

• Descripción de la imagen utilizando Anthropic Claude Vision, OpenAI GPT-4 Vision o Cloudflare Workers AI llava-1.5-7b-hf

• Fácil integración con Claude Desktop, Cursor y otros clientes compatibles con MCP

• Soporte para la implementación de Docker

• Soporte para la instalación de uvx

• Compatibilidad con múltiples formatos de imagen (JPEG, PNG, GIF, WebP)

• Proveedores primarios y de respaldo configurables

• Compatibilidad con entrada de imágenes basada en archivos y Base64

• Extracción de texto opcional mediante Tesseract OCR

Requisitos

• Python 3.8 o superior

• Tesseract OCR (opcional): necesario para la función de extracción de texto

  • Windows: Descargar e instalar desde UB-Mannheim/tesseract

  • Linux: sudo apt-get install tesseract-ocr

  • macOS: brew install tesseract

Instalación

Opción 1: Usar uvx (recomendado para Claude Desktop y Cursor)

1. Instalar el administrador de paquetes uv :

pip install uv

2. Instalar el paquete con uvx:

uvx install mcp-image-recognition

3. Cree y configure su archivo de entorno como se describe en la sección Configuración

Opción 2: Usar Docker

docker pull zudsniper/mcp-image-recognition:latest

# Create a .env file first, then run:
docker run -it --env-file .env zudsniper/mcp-image-recognition

Opción 3: Desde la fuente

1. Clonar el repositorio:

git clone https://github.com/zudsniper/mcp-image-recognition.git
cd mcp-image-recognition

2. Crea y configura tu archivo de entorno:

cp .env.example .env
# Edit .env with your API keys and preferences

3. Construir el proyecto:

pip install -e .

Integración

Integración de escritorio de Claude

1. Vaya a Claude > Configuración > Desarrollador > Editar configuración > claude_desktop_config.json

2. Agregar configuración con variables de entorno en línea:

{
    "mcpServers": {
        "image-recognition": {
            "command": "uvx",
            "args": [
                "mcp-image-recognition"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

Integración del cursor

Vaya a Configuración del cursor > MCP y pegue con variables de entorno:

VISION_PROVIDER=openai OPENAI_API_KEY=your-api-key OPENAI_MODEL=gpt-4o uvx mcp-image-recognition

Integración de Docker

Opción 1: Usar la imagen de DockerHub

Agregue esto a su configuración de Claude Desktop con entorno en línea:

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "zudsniper/mcp-image-recognition:latest"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key", 
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

Para la configuración de Cloudflare:

"env": {
    "VISION_PROVIDER": "cloudflare",
    "CLOUDFLARE_API_KEY": "your-api-key",
    "CLOUDFLARE_ACCOUNT_ID": "your-account-id"
}

Uso

Ejecutar el servidor directamente

Si se instala con pip/uvx:

mcp-image-recognition

Desde el directorio de origen:

python -m image_recognition_server.server

Usando Docker:

docker run -it --env-file .env zudsniper/mcp-image-recognition

Comience en modo de desarrollo con el Inspector MCP:

npx @modelcontextprotocol/inspector mcp-image-recognition

Herramientas disponibles

1. describe_image

   • Propósito : Analizar imágenes cargadas directamente al chat.

   • Entrada : datos de imagen codificados en Base64

   • Salida : Descripción detallada de la imagen.

   • Ideal para : imágenes cargadas directamente en Claude, Cursor u otras interfaces de chat

2. describe_image_from_file

   • Propósito : Procesar archivos de imagen locales del sistema de archivos

   • Entrada : Ruta a un archivo de imagen

   • Salida : Descripción detallada de la imagen.

   • Ideal para : desarrollo local con acceso al sistema de archivos

   • Nota : Cuando se ejecuta en Docker, se requiere mapeo de volumen (consulte la sección Acceso a archivos de Docker)

3. describe_image_from_url

   • Propósito : Analizar imágenes desde URLs web sin descargarlas manualmente

   • Entrada : URL de una imagen de acceso público

   • Salida : Descripción detallada de la imagen.

   • Ideal para : imágenes web, capturas de pantalla o cualquier cosa con una URL pública.

   • Nota : utiliza encabezados similares a los del navegador para evitar la limitación de velocidad.

Configuración del entorno

• ANTHROPIC_API_KEY : Su clave API antrópica.

• OPENAI_API_KEY : Su clave API de OpenAI.

• CLOUDFLARE_API_KEY : Su clave API de Cloudflare.

• CLOUDFLARE_ACCOUNT_ID : Su ID de cuenta de Cloudflare.

• VISION_PROVIDER : Proveedor de visión principal ( anthropic , openai o cloudflare ).

• FALLBACK_PROVIDER : Proveedor de respaldo opcional.

• LOG_LEVEL : Nivel de registro (DEBUG, INFO, WARNING, ERROR).

• ENABLE_OCR : habilita la extracción de texto OCR de Tesseract ( true o false ).

• TESSERACT_CMD : Ruta personalizada opcional al ejecutable de Tesseract.

• OPENAI_MODEL : Modelo OpenAI (predeterminado: gpt-4o-mini ). Se puede usar el formato OpenRouter para otros modelos (p. ej., anthropic/claude-3.5-sonnet:beta ).

• OPENAI_BASE_URL : URL base personalizada opcional para la API de OpenAI. Establézcala en https://openrouter.ai/api/v1 para OpenRouter.

• OPENAI_TIMEOUT : Tiempo de espera personalizado opcional (en segundos) para la API de OpenAI.

• CLOUDFLARE_MODEL : modelo de IA de Cloudflare Workers (predeterminado: @cf/llava-hf/llava-1.5-7b-hf ).

• CLOUDFLARE_MAX_TOKENS : Número máximo de tokens a generar (predeterminado: 512 ).

• CLOUDFLARE_TIMEOUT : Tiempo de espera para las solicitudes de API de Cloudflare en segundos (valor predeterminado: 60 ).

Uso de OpenRouter

OpenRouter permite acceder a varios modelos mediante el formato de la API de OpenAI. Para usar OpenRouter, siga estos pasos:

1. Obtenga una clave API de OpenAI de OpenRouter.

2. Establezca OPENAI_API_KEY en su archivo .env en su clave API de OpenRouter.

3. Establezca OPENAI_BASE_URL en https://openrouter.ai/api/v1 .

4. Establezca OPENAI_MODEL en el modelo deseado utilizando el formato OpenRouter (por ejemplo, anthropic/claude-3.5-sonnet:beta ).

5. Establezca VISION_PROVIDER en openai .

Modelos predeterminados

• Antrópico: claude-3.5-sonnet-beta

• OpenAI: gpt-4o-mini

• IA de los trabajadores de Cloudflare: @cf/llava-hf/llava-1.5-7b-hf

• OpenRouter: utilice el formato anthropic/claude-3.5-sonnet:beta en OPENAI_MODEL .

Desarrollo

Guía de configuración del desarrollo

Configuración del entorno de desarrollo

1. Clonar el repositorio:

git clone https://github.com/zudsniper/mcp-image-recognition.git
cd mcp-image-recognition

2. Configuración con uv (recomendado):

# Install uv if not installed
pip install uv

# Create virtual environment and install deps
uv venv
uv venv activate
uv pip install -e .
uv pip install -e ".[dev]"

Configuración alternativa con pip:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
# Or alternatively:
pip install -r requirements.txt
pip install -r requirements-dev.txt

3. Configurar el entorno:

cp .env.example .env
# Edit .env with your API keys

Desarrollo de VS Code / DevContainer

1. Instalar VS Code con la extensión Contenedores Remotos

2. Abra la carpeta del proyecto en VS Code

3. Haga clic en "Reabrir en el contenedor" cuando se le solicite

4. El devcontainer se compilará y se abrirá con todas las dependencias instaladas

Uso del contenedor de desarrollo con Claude Desktop

1. Pasar el archivo de entorno a Docker Compose:

# Modern Docker Compose V2 syntax
docker compose --env-file .env up -d

2. Agregue esto a su configuración de Claude Desktop:

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "exec",
                "-i",
                "mcp-image-recognition-dev",
                "python",
                "-m",
                "image_recognition_server.server"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

Probar sus cambios localmente

1. Ejecute el servidor MCP en modo de desarrollo:

# Install the MCP Inspector if you haven't already
npm install -g @modelcontextprotocol/inspector

# Start the server with the Inspector
npx @modelcontextprotocol/inspector mcp-image-recognition

2. El Inspector proporciona una interfaz web (normalmente en http://localhost:3000 ) donde puedes:

   • Envía solicitudes a tus herramientas

   • Ver registros de solicitud/respuesta

   • Depurar problemas con su implementación

3. Pruebe herramientas específicas:

   • Para describe_image : Proporcione una imagen codificada en base64

   • Para describe_image_from_file : proporcione una ruta a un archivo de imagen local

   • Para describe_image_from_url : Proporcione una URL a una imagen

Integración con Claude Desktop para realizar pruebas

1. Modifique temporalmente la configuración de Claude Desktop para usar su versión de desarrollo:

{
    "mcpServers": {
        "image-recognition": {
            "command": "python",
            "args": [
                "-m", "image_recognition_server.server"
            ],
            "cwd": "/path/to/your/mcp-image-recognition",
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

2. Reinicie Claude Desktop para aplicar los cambios

3. Prueba cargando imágenes o proporcionando URLs de imágenes en tus conversaciones

Ejecución de pruebas

Ejecutar todas las pruebas:

run.bat test

Ejecutar un conjunto de pruebas específico:

run.bat test server
run.bat test anthropic
run.bat test openai

Soporte de Docker

Construya la imagen de Docker:

docker build -t mcp-image-recognition .

Ejecute el contenedor:

docker run -it --env-file .env mcp-image-recognition

Limitaciones de acceso a archivos de Docker

Al ejecutar el servidor MCP en Docker, la herramienta describe_image_from_file solo puede acceder a los archivos dentro del contenedor. De forma predeterminada, el contenedor no tiene acceso a los archivos del sistema host. Para habilitar el acceso a los archivos locales, debe asignar directorios explícitamente al configurar el servidor MCP.

Nota importante : Al usar Claude Desktop, Cursor u otras plataformas donde se suben imágenes a los chats, estas se almacenan en los servidores de Anthropic y no son accesibles directamente al servidor MCP a través de una ruta del sistema de archivos. En estos casos, debe:

1. Utilice la herramienta describe_image (que funciona con imágenes codificadas en base64) para las imágenes cargadas directamente en el chat

2. Utilice la nueva herramienta describe_image_from_url para imágenes alojadas en línea

3. Para los archivos locales, asegúrese de que el directorio esté asignado correctamente al contenedor Docker

Asignación de directorios locales a Docker

Para darle al contenedor Docker acceso a carpetas específicas en su sistema, modifique la configuración de su servidor MCP para incluir la asignación de volúmenes:

{
    "mcpServers": {
        "image-recognition": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-v", "/path/on/host:/path/in/container",
                "zudsniper/mcp-image-recognition:latest"
            ],
            "env": {
                "VISION_PROVIDER": "openai",
                "OPENAI_API_KEY": "your-api-key",
                "OPENAI_MODEL": "gpt-4o"
            }
        }
    }
}

Por ejemplo, para mapear su carpeta de Descargas:

• Windows: -v "C:\\Users\\YourName\\Downloads:/app/images"

• macOS/Linux: -v "/Users/YourName/Downloads:/app/images"

Luego acceda a los archivos utilizando la ruta del contenedor: /app/images/your_image.jpg

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

Uso de Cloudflare Workers AI

Para utilizar Cloudflare Workers AI para el reconocimiento de imágenes:

1. Inicie sesión en el panel de Cloudflare y seleccione su cuenta.

2. Vaya a IA > IA de trabajadores .

3. Seleccione Usar API REST y cree un token de API con permisos de Workers AI.

4. Establezca lo siguiente en su archivo .env :

   • CLOUDFLARE_API_KEY : Su token de API de Cloudflare

   • CLOUDFLARE_ACCOUNT_ID : ID de su cuenta de Cloudflare

   • VISION_PROVIDER : Establecer en cloudflare

   • CLOUDFLARE_MODEL : Opcional, el valor predeterminado es @cf/llava-hf/llava-1.5-7b-hf

Uso con asistentes de IA

Una vez configurado, su asistente de IA (Claude, por ejemplo) puede analizar imágenes mediante:

1. Sube una imagen directamente en el chat

2. El asistente utilizará automáticamente el servidor MCP para analizar la imagen.

3. El asistente describirá la imagen en detalle basándose en la salida de la API de visión.

Ejemplo de mensaje después de cargar una imagen:

Please describe this image in detail.

También puedes personalizar el mensaje según tus necesidades específicas:

What text appears in this image?

o

Is there any safety concern in this image?

Historial de versiones

• 1.2.1 (28/03/2025): Documentación reorganizada y flujo de trabajo de devcontainer mejorado

• 1.2.0 (28/03/2025): Se corrigió la obtención de imágenes de URL con encabezados httpx y del navegador, se agregó compatibilidad con devcontainer

• 1.1.0 (28/03/2025): Descripciones de herramientas mejoradas para una mejor selección, SDK de OpenAI actualizado a la última versión

• 1.0.1 (28/03/2025): Se agregó reconocimiento de imágenes basado en URL, se mejoró la documentación de Docker y se corrigieron las limitaciones del sistema de archivos.

• 1.0.0 (28/03/2025): Se agregó compatibilidad con Cloudflare Workers AI con el modelo llava-1.5-7b-hf, compatibilidad con Docker y compatibilidad con uvx.

• 0.1.2 (2025-02-20): Se mejoró el manejo de errores de OCR y se agregó una cobertura de prueba integral para la funcionalidad de OCR.

• 0.1.1 (19/02/2025): Se agregó compatibilidad con Tesseract OCR para la extracción de texto de imágenes (función opcional)

• 0.1.0 (19/02/2025): Versión inicial con compatibilidad con visión antrópica y OpenAI

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Lanzamiento de nuevas versiones

Para lanzar una nueva versión:

1. Actualizar la versión en pyproject.toml y setup.py

2. Enviar cambios a la rama release

3. Las acciones de GitHub harán lo siguiente automáticamente:

   • Ejecutar pruebas

   • Crear y enviar imágenes de Docker

   • Publicar en PyPI

   • Crear una versión de GitHub

Secretos de repositorio necesarios para CI/CD:

• DOCKERHUB_USERNAME - Nombre de usuario de Docker Hub

• DOCKERHUB_TOKEN - Token de acceso a Docker Hub

• PYPI_API_TOKEN - Token API de PyPI