visionMCP 👁️

Los ojos de un LLM de razonamiento más grande.

visionMCP es un servidor del Model Context Protocol que proporciona visión real a cualquier agente capaz de usar MCP. Un modelo de razonamiento exclusivamente textual puede delegar en este servidor todo aquello que no puede ver: describir una captura de pantalla, responder a una pregunta sobre una foto, hacer OCR de un documento o comparar dos imágenes. El servidor se encarga de ver y devuelve texto.

Funciona con los tres principales backends de visión, elegidos en tiempo de ejecución a partir de un único config.json:

Características

• 🔍 Cuatro herramientas de visión para que las llame un LLM de razonamiento:

  • describe_image — descripción completa en lenguaje natural

  • ask_about_image — preguntas y respuestas específicas sobre cualquier imagen

  • extract_text — OCR / transcripción

  • compare_images — comparación lado a lado

• 🖼️ Se acepta cualquier fuente: rutas de archivo locales, URL http(s) y URIs data: en base64.

• 📦 Sin preparación de imágenes: las imágenes sobredimensionadas se reducen automáticamente y se recodifican como JPEG para ajustarse a los límites de carga del proveedor.

• 🔌 Tres transportes: stdio (predeterminado, para clientes MCP locales), http (HTTP transmisible para alojamiento remoto) o sse (Eventos enviados por el servidor, heredados).

• ⚙️ Un único config.json controla el proveedor, la clave API, la URL de la API y el modelo. Las variables de entorno y los indicadores de línea de comandos pueden sobrescribir cualquier cosa.

• 🚀 Gestionado con uv, instalable, ejecutable y alojable.

Related MCP server: depu-img-mcp

Inicio rápido

1. Instalar

Requiere uv y Python ≥ 3.10.

cd visionMCP
uv sync

2. Configurar

El config.json incluido ya funciona con un Ollama local. Cambia de proveedor editando el archivo:

// config.json
{
  "provider": "openai",                  // "ollama" | "openai" | "anthropic"
  "api_key": "sk-...",                   // or leave "" and export OPENAI_API_KEY
  "api_url": "",                         // "" = provider default
  "model": ""                            // "" = provider default
}

Consulta docs/configuration.md para conocer todas las opciones, y docs/providers.md para la configuración específica de cada proveedor.

Seguridad: mantén las claves API reales fuera de git. Copia config.json a config.local.json (se ignora automáticamente) o usa variables de entorno. El servidor nunca registra tu clave.

3. Ejecutar

uv run vision-mcp                        # stdio transport (default)
uv run vision-mcp --transport http --host 0.0.0.0 --port 8100   # host remotely
uv run vision-mcp --show-config          # print resolved config (key masked)

Conexión con un cliente MCP

opencode (opencode.json)

{
  "mcpServers": {
    "visionMCP": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "visionMCP": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Cliente MCP genérico (stdio)

{
  "mcpServers": {
    "visionMCP": {
      "command": "/path/to/visionMCP/.venv/bin/vision-mcp",
      "args": ["--config", "/path/to/visionMCP/config.json"]
    }
  }
}

El servidor nunca envía el contenido de la imagen a la API de visión más allá de lo que proporciona la llamada a la herramienta. Los bytes de la imagen se mantienen en memoria y nunca se escriben en disco.

Referencia de herramientas

Un argumento image acepta cualquiera de:

/path/to/photo.png          # local file
https://example.com/x.jpg   # URL (downloaded at call time)
data:image/png;base64,iVBORw0KGgo...   # base64 data URI

Cómo funciona

Todo pasa por una única función en src/vision_mcp/pipeline.py:

image (path / URL / data URI)  →  base64 + mime  →  vision model  →  text
        _read()                     _encode()         API[provider]    look()

Las herramientas del servidor son envoltorios ligeros: pipeline.look(cfg, [image], prompt).

Documentación

• Referencia de configuración — todas las opciones de configuración, variables de entorno y reglas de precedencia

• Configuración de proveedores — Ollama, OpenAI y Anthropic, paso a paso

• Despliegue — alojamiento sobre HTTP/SSE, Docker, endurecimiento

Desarrollo

uv sync --group dev
uv run ruff check .
uv run pytest

Licencia

MIT