Vision MCP Server

Un servidor de Model Context Protocol (MCP) que aporta capacidad de visión a agentes conectados a modelos no multimodales (DeepSeek, GPT-4 antiguo, modelos locales pequeños, etc.): el agente entrega una imagen a la herramienta MCP, el servidor llama a un modelo de visión y devuelve texto.

Compatible con los principales proveedores de China y EE. UU., además de cualquier endpoint compatible con OpenAI. SDK oficiales primero, abstracción antes que implementación, incorporación de proveedores sin fricción.

Documentación en chino en README.zh-CN.md

Características

• 4 herramientas: analyze_image / describe_image / ocr_image / list_providers, todas devuelven texto Markdown plano

• 13 proveedores integrados: OpenAI / Anthropic / Google Gemini / Qwen (DashScope) / Zhipu / Doubao (Volcengine) / ERNIE (Qianfan) / StepFun / Ollama / Alibaba Bailian / SiliconFlow / OpenRouter / endpoint personalizado compatible con OpenAI

• Tres formatos de imagen: ruta local / URL http(s) / base64 (URI de datos o base64 sin procesar), detectados automáticamente

• Cadena de respaldo de tres niveles: SDK oficial → endpoint compatible con OpenAI → fetch nativo (ver SPEC §1)

• Sin estado: cada llamada es independiente; las imágenes y los resultados nunca se almacenan en caché; las claves solo se leen de variables de entorno

Related MCP server: vision-mcp

Inicio rápido

Opción A: npx (publicado en npm, sin necesidad de repositorio)

npx -y @inferai/vision-mcp

Opción B: compilación local

git clone <repo> && cd vision-mcp
pnpm install
pnpm build
node dist/index.js

Ejemplos de configuración de MCP (stdio)

El servidor utiliza el transporte stdio: el cliente MCP inicia el proceso e intercambia mensajes JSON-RPC a través de stdin/stdout. Configúralo donde tu cliente defina los servidores MCP:

• Claude Code: .mcp.json a nivel de proyecto o ~/.claude.json a nivel de usuario (clave mcpServers)

• Claude Desktop: claude_desktop_config.json

• Cualquier cliente MCP (Cursor, agentes propios, etc.): misma estructura

Versión npx (disponible después de publicar el paquete):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@inferai/vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

Desarrollo local (ajusta la ruta; --env-file-if-exists=.env carga .env de forma nativa):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["--env-file-if-exists=.env", "/absolute/path/to/vision-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Con argumentos de inicio (anula los valores predeterminados del proveedor mediante argv, ver más abajo):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@inferai/vision-mcp",
        "--default-provider=dashscope",
        "--siliconflow-api-key=sk-...",
        "--siliconflow-model=Qwen/Qwen2.5-VL-7B-Instruct"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

Notas sobre stdio:

• stdout solo transporta el protocolo MCP — el servidor nunca imprime registros ahí; los diagnósticos van a stderr

• el cliente gestiona el ciclo de vida del proceso (inicio al arrancar, terminación al salir); no se necesita demonio

• la primera ejecución de npx descarga el paquete y puede tardar unos segundos

• las variables de entorno también pueden provenir del shell si el cliente las hereda (sin necesidad de bloque env)

Depura con MCP Inspector:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js --xxx-api-key=xxx --xxx2-api-key=xxx

Configuración de variables

1. Bloque env de la configuración MCP (recomendado, el más fiable entre plataformas) — escribe las variables en el objeto env anterior

2. Archivo .env (desarrollo local) — copia .env.example a .env, complétalo y luego ejecuta node --env-file-if-exists=.env dist/index.js (nativo en Node 22, sin necesidad de dotenv)

3. Exportación en el shell — export OPENAI_API_KEY=sk-xxx y luego ejecuta

Los proveedores sin claves aparecen como no disponibles en list_providers e informan de la variable que falta al ser llamados.

Publicación (antes de que funcione npx)

pnpm publish          # or pnpm release (changeset flow)

Variables de entorno

El API_KEY, BASE_URL y MODEL de cada proveedor admiten anulaciones mediante variables de entorno (convención: <PROVIDER_PREFIX>_API_KEY / <PROVIDER_PREFIX>_BASE_URL / <PROVIDER_PREFIX>_MODEL):

? = opcional (tiene un valor predeterminado integrado); * = obligatorio.

Configuración global:

Cadena de respaldo

Cuando hay varios proveedores disponibles, las llamadas recorren la cadena de prioridad: predeterminado configurado → lista VISION_MCP_PROVIDER_PRIORITY → orden de la tabla (los proveedores no disponibles se omiten).

• cada proveedor se reintenta hasta VISION_MCP_MAX_RETRIES veces ante errores del proveedor (fallos del servicio ascendente, tiempos de espera)

• cuando un proveedor agota sus reintentos, se prueba el siguiente proveedor disponible de la cadena, hasta VISION_MCP_MAX_FALLBACKS respaldos

• solo los errores del proveedor activan reintento/respaldo; los errores de configuración o de imagen fallan rápidamente

• un argumento provider solicitado explícitamente se prueba solo (sin respaldo)

• cuando todo falla, el error enumera cada proveedor intentado y su último error

También disponible como argv: --provider-priority=..., --max-retries=N, --max-fallbacks=N (superan a las variables de entorno).

Argumentos de inicio de MCP (argv)

El apiKey / baseUrl / model de cada proveedor se puede anular mediante argumentos de inicio (prioridad superior a las variables de entorno), formato --<provider>-<field>:

node dist/index.js \
  --openai-api-key=sk-xxx \
  --openai-base-url=https://my-gateway.example.com/v1 \
  --openai-model=gpt-4o-mini \
  --dashscope-api-key=sk-xxx \
  --default-provider=dashscope

• Global: --default-provider <nombre> / --default-model <nombre>

• Por proveedor: --<provider>-api-key, --<provider>-base-url, --<provider>-model (funcionan tanto con signo igual como con espacio)

• Cualquier servicio de terceros compatible con OpenAI: conéctalo en una línea con --openai-compat-base-url + --openai-compat-api-key + --openai-compat-model; o apunta el base-url de cualquier proveedor integrado a un espejo/proxy

Prioridad: argumentos de herramienta provider/model > argumentos de inicio (por proveedor > predeterminado global) > variables de entorno > valores predeterminados integrados del proveedor.

Herramientas

image acepta: ruta local / URL http(s):// / URI data: / base64 sin procesar, detectado automáticamente.

Nota de seguridad: las descargas por URL están protegidas contra SSRF — cada salto (incluidas las redirecciones) se valida y las URL que resuelven a direcciones loopback, privadas o link-local se bloquean (la pista en el error explica el motivo).

Integración de proveedores (cadena de respaldo de tres niveles)

Añadir un proveedor: para endpoints compatibles con OpenAI, añade una fila a RULES en src/core/config.ts y una asignación en la tabla de fábrica en src/index.ts — cero código nuevo. Implementaciones con SDK oficial o fetch nativo: consulta SPEC §1.

Desarrollo

pnpm check        # biome checks
pnpm test         # rstest unit tests (injected mocks, no network)
pnpm build        # rslib build

Pruebas de humo con llamadas reales (solo se ejecutan contra proveedores cuyas claves están configuradas; se omiten en caso contrario):

OPENAI_API_KEY=sk-... pnpm exec rstest tests/e2e

Arquitectura

src/
├── index.ts            # Entry: composition root, stdio startup
├── core/               # Abstraction: interfaces / image loading / config / registry
├── providers/          # Adapters: official SDK or compatible endpoints, protocol conversion only
└── server/tools.ts     # MCP tool layer: zod validation + error mapping

Especificación completa: SPEC.md.