mcp-six-eyes

Servidor MCP que da a los agentes de IA solo de texto la capacidad de entender imágenes, incluidos chats con varias imágenes como «consulta la imagen 1 y 2» o «compara estas capturas de pantalla».

Los modelos solo de texto no pueden ver píxeles. Este servidor cubre esa carencia: los agentes llaman a herramientas de visión, el servidor habla con una API multimodal y el agente recibe texto plano.

Agent (text-only)
   │  tool call: analyze / compare / refer / ocr / …
   ▼
mcp-six-eyes (this server)
   │  1..N images: path | URL | base64  (labels: 1, 2, before, …)
   ▼
Vision API (OpenAI / Anthropic / Gemini / OpenRouter / custom)
   │
   ▼
Plain-text description / OCR / comparison / structured extract
   │
   ▼
Agent continues reasoning with text

Por qué funciona

MCP expone herramientas que un agente puede llamar. El agente nunca necesita visión nativa:

1. El usuario sube o señala una o más imágenes

2. El agente llama a una herramienta de visión con esas fuentes (y etiquetas opcionales)

3. El servidor carga la(s) imagen(es) y las envía a un modelo multimodal

4. El servidor devuelve solo texto, con etiquetas de imagen estables

5. El agente solo de texto usa ese texto como cualquier otro resultado de herramienta

Related MCP server: MCP Vision Server

Herramientas

Entradas de imagen

Toda herramienta de imagen acepta:

• Individual: image: ruta local, file://, http(s), URL de datos o base64

• Múltiple: images: array de fuentes o objetos { source, label?, mimeType? }

• Puedes pasar ambas; se combinan

Las etiquetas por defecto son "1", "2", … de modo que las instrucciones del agente como «compara la imagen 1 y 2» se asignan limpiamente. Las etiquetas personalizadas también funcionan ("before", "after", "fig-a").

# one image
analyze_image({ image: "./shot.png", prompt: "What failed?" })

# multi-image with default labels 1..n
compare_images({
  images: ["./a.png", "./b.png"],
  prompt: "What changed in the error state?"
})

# multi-image with explicit labels (best for long threads)
refer_images({
  images: [
    { source: "./login.png", label: "1" },
    { source: "./dashboard.png", label: "2" }
  ],
  prompt: "Using image 1 and image 2, is the user authenticated?"
})

Formas de fuente admitidas:

• ruta de archivo local (/path/to/image.png o C:\path\to\image.png)

• URI file://

• URL http(s)

• URL de datos (data:image/png;base64,...)

• base64 sin procesar (pasa mimeType cuando sea posible)

Requisitos

• Node.js 20+

• Una clave de API con capacidad de visión (OpenAI, Anthropic, Google, OpenRouter o cualquier endpoint compatible con OpenAI)

Instalación

Publicado en npm como mcp-six-eyes.

npx -y mcp-six-eyes

O instala globalmente / como dependencia del proyecto:

npm install -g mcp-six-eyes
# or
npm install mcp-six-eyes

La mayoría de la gente lo conecta a un cliente MCP en lugar de ejecutarlo manualmente. Ejemplo de configuración de Claude Desktop / Cursor:

{
  "mcpServers": {
    "mcp-six-eyes": {
      "command": "npx",
      "args": ["-y", "mcp-six-eyes"],
      "env": {
        "VISION_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Por qué npx es popular aquí:

• sin instalación global

• el cliente inicia el servidor bajo demanda

• -y omite el aviso de instalación en la primera ejecución

• npm guarda en caché el paquete para lanzamientos posteriores

Desarrollo local

npm install
npm run build

Luego, o bien:

{
  "mcpServers": {
    "mcp-six-eyes": {
      "command": "npx",
      "args": ["-y", "."],
      "env": {
        "VISION_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

o apunta Node al punto de entrada compilado:

{
  "mcpServers": {
    "mcp-six-eyes": {
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "VISION_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Entorno

Establece las claves del proveedor en el bloque env del cliente MCP (recomendado) o en un .env local para desarrollo.

Configuración mínima de OpenAI:

VISION_PROVIDER=openai
OPENAI_API_KEY=sk-...

Modelo / límites opcionales:

VISION_MODEL=gpt-4o-mini
VISION_MAX_IMAGES=10
VISION_MAX_IMAGE_BYTES=20971520
VISION_CACHE_MAX_ENTRIES=200

El servidor habla MCP sobre stdio. No escribas registros de aplicación en stdout.

Caché

Las llamadas de visión se memorizan por contenido, en memoria. La clave de caché genera un hash de los bytes reales de la imagen más la tarea, la instrucción, las etiquetas y el límite de tokens (no la cadena de la fuente), de modo que un modelo que vuelva a llamar a describe_image (o a cualquier herramienta de visión) sobre la misma imagen recibe al instante la respuesta anterior, marcada como Cached: yes, sin volver a facturar a la API de visión.

• Por defecto: VISION_CACHE_MAX_ENTRIES=200 (acotada, se expulsa primero la más antigua)

• Establece VISION_CACHE_MAX_ENTRIES=0 para desactivarla

• La primera respuesta gana para una clave dada; un archivo o URL cambiado produce una clave nueva

• Las respuestas fallidas y de respaldo nunca se guardan en caché

• La caché vive solo durante la vida del proceso (sin persistencia en disco)

Notas para clientes

Claude Desktop

Archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %AppData%\Claude\claude_desktop_config.json

Usa el bloque npx de Inicio rápido con npx.

Cursor

Añade el mismo bloque de servidor a .cursor/mcp.json (proyecto) o a tu configuración global de MCP de Cursor.

Otros hosts MCP con stdio

Cualquier host que pueda lanzar:

npx -y mcp-six-eyes

y pasar variables de entorno funcionará.

Proveedores

Respaldo opcional:

VISION_FALLBACK_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Ejemplo de uso con agentes

Captura de pantalla individual

User: What's wrong in this screenshot? ./screenshots/build-error.png

Agent → ocr_image({ image: "./screenshots/build-error.png" })
Agent → analyze_image({
  image: "./screenshots/build-error.png",
  prompt: "Explain the error and suggest a fix"
})
Agent → answers in plain text

Multiimagen: referir / comparar

User: I uploaded two shots. Compare image 1 and 2. Did the fix work?

Agent → compare_images({
  images: [
    { source: "./before.png", label: "1" },
    { source: "./after.png", label: "2" }
  ],
  prompt: "Did the red error banner disappear after the fix?"
})

User: Refer image 1 and image 2. Which CTA is primary?

Agent → refer_images({
  images: [
    { source: "./landing-a.png", label: "1" },
    { source: "./landing-b.png", label: "2" }
  ],
  prompt: "Which image has the stronger primary CTA and why?"
})

Flujo de interfaz, gráfico, diagrama, extracción estructurada

inspect_ui({
  images: ["./step1.png", "./step2.png", "./step3.png"],
  prompt: "Describe the checkout flow and any friction"
})

read_chart({
  image: "https://example.com/revenue.png",
  prompt: "Summarize the trend and call out outliers"
})

explain_diagram({
  image: "./architecture.png",
  prompt: "List services and data flow"
})

extract_from_images({
  image: "./receipt.jpg",
  schema: "{\"merchant\":string,\"date\":string,\"total\":number,\"items\":[{\"name\":string,\"price\":number}]}"
})

Arquitectura

src/
  index.ts                 MCP server + tools
  config.ts                env/provider config
  image.ts                 path/URL/base64 loader + multi-image labels
  prompts.ts               task prompts (analyze/describe/ocr/compare/...)
  providers/
    index.ts               provider router + fallback
    openai-compatible.ts   OpenAI / OpenRouter / custom (multi-image)
    anthropic.ts           Claude vision (multi-image)
    google.ts              Gemini vision (multi-image)
    types.ts               shared contracts
test/                      unit tests (node:test, mocked providers)
assets/
  logo.png                 project logo

Notas de diseño

• Herramientas, no recursos: la comprensión de imágenes es una acción con efectos secundarios (coste de API), por lo que se expone como herramientas.

• Salida solo de texto: los modelos anfitriones sin visión solo necesitan bloques de contenido de texto.

• Multiimagen etiquetada: los agentes en chats de interfaz hablan de «imagen 1/2»; las etiquetas mantienen estable ese anclaje.

• Herramientas específicas por tarea: comparar / referir / interfaz / gráfico / diagrama / extraer superan a un solo mega-prompt para la selección de herramientas.

• Transporte stdio: la integración local más simple para agentes de escritorio.

• Sin registro en stdout: stdout está reservado para JSON-RPC; los diagnósticos van a stderr.

• Abstracción de proveedor: cambia de backend sin alterar los nombres de herramienta que el agente aprende.

Desarrollo

npm install
npm test
npm start

Depura con el Inspector MCP:

npx @modelcontextprotocol/inspector node ./build/index.js

Consulta CONTRIBUTING.md para las directrices de PR y código.

Enlaces

• npm: mcp-six-eyes

• Mantenedor: rimunace

Flujo de publicación

Ruta del mantenedor tras cambios locales:

# one-time
npm login

# bump version + CHANGELOG, then ship
npm test
npm publish --access public

Ayudante opcional (pruebas y luego npm publish):

npm run release

Seguridad

• Las claves de API permanecen en variables de entorno / configuración del cliente, nunca en las respuestas de las herramientas

• Las descargas de URL remotas son entradas explícitas de herramienta; trata con cuidado las URL no confiables

• Las imágenes grandes se rechazan mediante VISION_MAX_IMAGE_BYTES (20MB por defecto)

• El número de imágenes por llamada está limitado mediante VISION_MAX_IMAGES (10 por defecto)

• La caché de respuestas guarda solo hashes de contenido y texto de resultado en memoria; nada se persiste en disco

Política completa: SECURITY.md.

Contribuciones

Se aceptan incidencias y pull requests. Por favor, ejecuta npm test antes de abrir una PR y lee CONTRIBUTING.md.

Licencia

MIT