Moondream

Un modelo de lenguaje visual para análisis de imágenes, que incluye subtitulado, VQA y detección de objetos.

GitHub
47
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Moondream

Un servidor FastMCP para Moondream, un modelo de lenguaje de visión por IA. Este servidor proporciona capacidades de análisis de imágenes, incluyendo subtitulado, respuesta a preguntas visuales, detección de objetos y señalización visual a través del Model Context Protocol (MCP).

Características

  • 🖼️ Subtitulado de imágenes: Genera subtítulos cortos, normales o detallados para imágenes.
  • ❓ Respuesta a preguntas visuales: Haz preguntas en lenguaje natural sobre imágenes.
  • 🔍 Detección de objetos: Detecta y localiza objetos específicos con cuadros delimitadores.
  • 📍 Señalización visual: Obtén coordenadas precisas de objetos en imágenes.
  • 🔗 Soporte de URL: Procesa imágenes tanto de archivos locales como de URLs remotas.
  • ⚡ Procesamiento por lotes: Analiza múltiples imágenes de manera eficiente.
  • 🚀 Optimización de dispositivo: Detección y optimización automática para CPU, CUDA y MPS (Apple Silicon).

Instalación

Requisitos previos

  • Python 3.10 o superior
  • PyTorch 2.0+ (con soporte de dispositivo adecuado)

Usando uvx (Recomendado para Claude Desktop)

# Run without installation
uvx moondream-mcp

# Or specify a specific version
uvx moondream-mcp==1.0.2

Instalar desde PyPI

pip install moondream-mcp

Instalar desde el código fuente

git clone https://github.com/ColeMurray/moondream-mcp.git
cd moondream-mcp
pip install -e .

Instalación de desarrollo

git clone https://github.com/ColeMurray/moondream-mcp.git
cd moondream-mcp
pip install -e ".[dev]"

Inicio rápido

Ejecutando el servidor

# Using uvx (no installation needed)
uvx moondream-mcp

# Using pip-installed command
moondream-mcp

# Or run directly with Python
python -m moondream_mcp.server

Integración con Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

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

Usando uvx (Recomendado)

{
  "mcpServers": {
    "moondream": {
      "command": "uvx",
      "args": ["moondream-mcp"],
      "env": {
        "MOONDREAM_DEVICE": "auto"
      }
    }
  }
}

Usando el comando instalado con pip

{
  "mcpServers": {
    "moondream": {
      "command": "moondream-mcp",
      "env": {
        "MOONDREAM_DEVICE": "auto"
      }
    }
  }
}

Configuración

El servidor se puede configurar usando variables de entorno:

Configuración del modelo

  • MOONDREAM_MODEL_NAME: Nombre del modelo (por defecto: vikhyatk/moondream2)
  • MOONDREAM_MODEL_REVISION: Revisión del modelo (por defecto: 2025-01-09)
  • MOONDREAM_TRUST_REMOTE_CODE: Confiar en código remoto (por defecto: true)

Configuración del dispositivo

  • MOONDREAM_DEVICE: Forzar dispositivo específico (cpu, cuda, mps, o auto)

Procesamiento de imágenes

  • MOONDREAM_MAX_IMAGE_SIZE: Dimensiones máximas de imagen (por defecto: 2048x2048)
  • MOONDREAM_MAX_FILE_SIZE_MB: Tamaño máximo de archivo en MB (por defecto: 50)

Rendimiento

  • MOONDREAM_TIMEOUT_SECONDS: Tiempo de espera de procesamiento (por defecto: 120)
  • MOONDREAM_MAX_CONCURRENT_REQUESTS: Máximo de solicitudes concurrentes (por defecto: 5)
  • MOONDREAM_ENABLE_STREAMING: Habilitar transmisión para subtítulos (por defecto: true)
  • MOONDREAM_MAX_BATCH_SIZE: Tamaño máximo de lote para operaciones por lotes (por defecto: 10)
  • MOONDREAM_BATCH_CONCURRENCY: Límite de procesamiento por lotes concurrente (por defecto: 3)
  • MOONDREAM_ENABLE_BATCH_PROGRESS: Habilitar informe de progreso para operaciones por lotes (por defecto: true)

Red (para URLs)

  • MOONDREAM_REQUEST_TIMEOUT_SECONDS: Tiempo de espera de solicitud HTTP (por defecto: 30)
  • MOONDREAM_MAX_REDIRECTS: Máximo de redirecciones HTTP (por defecto: 5)
  • MOONDREAM_USER_AGENT: Cabecera HTTP User-Agent

Herramientas disponibles

1. caption_image

Genera subtítulos para imágenes.

Parámetros:

  • image_path (string): Ruta al archivo de imagen o URL
  • length (string): Longitud del subtítulo - "short", "normal", o "detailed"
  • stream (boolean): Si transmitir la generación de subtítulos

Ejemplo:

{
  "image_path": "https://example.com/image.jpg",
  "length": "detailed",
  "stream": false
}

2. query_image

Haz preguntas sobre imágenes.

Parámetros:

  • image_path (string): Ruta al archivo de imagen o URL
  • question (string): Pregunta a hacer sobre la imagen

Ejemplo:

{
  "image_path": "/path/to/image.jpg",
  "question": "How many people are in this image?"
}

3. detect_objects

Detecta objetos específicos en imágenes.

Parámetros:

  • image_path (string): Ruta al archivo de imagen o URL
  • object_name (string): Nombre del objeto a detectar

Ejemplo:

{
  "image_path": "https://example.com/photo.jpg",
  "object_name": "person"
}

4. point_objects

Obtén coordenadas de objetos en imágenes.

Parámetros:

  • image_path (string): Ruta al archivo de imagen o URL
  • object_name (string): Nombre del objeto a localizar

Ejemplo:

{
  "image_path": "/path/to/image.jpg",
  "object_name": "car"
}

5. analyze_image

Herramienta de análisis de imágenes multipropósito.

Parámetros:

  • image_path (string): Ruta al archivo de imagen o URL
  • operation (string): Tipo de operación ("caption", "query", "detect", "point")
  • parameters (string): Cadena JSON con parámetros específicos de la operación

Ejemplo:

{
  "image_path": "https://example.com/image.jpg",
  "operation": "query",
  "parameters": "{\"question\": \"What is the weather like?\"}"
}

6. batch_analyze_images

Procesa múltiples imágenes en lote.

Parámetros:

  • image_paths (string): Matriz JSON de rutas de imágenes
  • operation (string): Operación a realizar en todas las imágenes
  • parameters (string): Cadena JSON con parámetros específicos de la operación

Ejemplo:

{
  "image_paths": "[\"image1.jpg\", \"image2.jpg\"]",
  "operation": "caption",
  "parameters": "{\"length\": \"short\"}"
}

Ejemplos de uso

Subtitulado básico de imágenes

# Using the caption_image tool
result = await caption_image(
    image_path="https://example.com/sunset.jpg",
    length="detailed"
)

Respuesta a preguntas visuales

# Ask about image content
result = await query_image(
    image_path="/path/to/family_photo.jpg",
    question="How many children are in this photo?"
)

Detección de objetos

# Detect faces in an image
result = await detect_objects(
    image_path="https://example.com/group_photo.jpg",
    object_name="face"
)

Procesamiento por lotes

# Process multiple images
result = await batch_analyze_images(
    image_paths='["img1.jpg", "img2.jpg", "img3.jpg"]',
    operation="caption",
    parameters='{"length": "normal"}'
)

Soporte de dispositivos

El servidor detecta y optimiza automáticamente el hardware disponible:

Apple Silicon (MPS)

  • Rendimiento óptimo en Macs M1/M2/M3
  • Gestión automática de memoria
  • Aceleración nativa

NVIDIA CUDA

  • Aceleración GPU para tarjetas NVIDIA
  • Gestión automática de memoria CUDA
  • Soporte de precisión mixta

Respaldo de CPU

  • Funciona en cualquier sistema
  • Optimizado para procesamiento multinúcleo
  • Menores requisitos de memoria

Manejo de errores

El servidor proporciona información detallada de errores:

{
  "success": false,
  "error_message": "Image file not found: /path/to/missing.jpg",
  "error_code": "IMAGE_PROCESSING_ERROR",
  "processing_time_ms": 15.2
}

Códigos de error comunes:

  • MODEL_LOAD_ERROR: Problemas al cargar el modelo Moondream
  • IMAGE_PROCESSING_ERROR: Problemas con archivos de imagen o URLs
  • INFERENCE_ERROR: Fallos de inferencia del modelo
  • INVALID_REQUEST: Parámetros o solicitudes no válidos

Consejos de rendimiento

  1. Usa tamaños de imagen apropiados: Redimensiona imágenes grandes antes de procesar
  2. Procesamiento por lotes: Usa batch_analyze_images para múltiples imágenes
  3. Optimización de dispositivo: Deja que el servidor detecte automáticamente el mejor dispositivo
  4. Solicitudes concurrentes: Ajusta MOONDREAM_MAX_CONCURRENT_REQUESTS según tu hardware
  5. Gestión de memoria: Monitorea el uso de memoria, especialmente con imágenes grandes

Solución de problemas

Problemas de carga del modelo

# Check PyTorch installation
python -c "import torch; print(torch.__version__)"

# Check device availability
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')"

Problemas de memoria

  • Reduce MOONDREAM_MAX_IMAGE_SIZE
  • Baja MOONDREAM_MAX_CONCURRENT_REQUESTS
  • Usa CPU en lugar de GPU para imágenes grandes

Problemas de red

  • Verifica la configuración del firewall para acceso a URLs
  • Aumenta MOONDREAM_REQUEST_TIMEOUT_SECONDS
  • Verifica los certificados SSL para URLs HTTPS

Desarrollo

Ejecutando pruebas

pytest tests/

Calidad del código

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Type checking
mypy src/

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Haz tus cambios
  4. Añade pruebas
  5. Ejecuta comprobaciones de calidad
  6. Envía una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.

Agradecimientos

Soporte

Nota: Este servidor requiere descargar el modelo Moondream en el primer uso, lo que puede tomar algún tiempo dependiendo de tu conexión a internet.