openrouter-mcp-multimodal

OpenRouter MCP Multimodal

El servidor MCP para agentes de IA multimodales.
Una instalación · 19 herramientas · más de 300 modelos de OpenRouter · texto, visión, audio y video — análisis y generación.

Inicio rápido · Herramientas · Ejemplos · Seguridad · Solución de problemas · Desarrollo · Publicación · Preguntas frecuentes

¿Qué es esto?

OpenRouter MCP Multimodal es un servidor de Model Context Protocol (MCP) de nivel de producción — listado en el registro oficial de MCP como io.github.stabgan/openrouter-multimodal. Conecta agentes de codificación de IA (Cursor, Claude Desktop, VS Code, Windsurf, Cline y otros) a la API unificada de LLM de OpenRouter a través de stdio.

A diferencia de los servidores MCP solo de texto, una sola instalación cubre la superficie multimodal completa:

Endurecimiento de producción: sandboxes de rutas de entrada/salida (incluidos archivos locales analyze_* a partir de v4.5.2), protecciones SSRF, errores estructurados con _meta.code, salidas estructuradas MCP 2025-06-18, iconos de herramientas (2025-11-25), notificaciones de progreso de video asíncronas y más de 1000 pruebas automatizadas (unitarias, simuladas, de regresión e integración en vivo).

Inicio rápido

1. Obtén una clave de API (el nivel gratuito funciona) → openrouter.ai/keys

2. Ejecuta el servidor

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

3. Añádelo a tu cliente MCP — copia un bloque JSON de Instalación en la configuración de tu cliente:

Usa el objeto mcpServers de Configuración manual a continuación.

No se requieren créditos para comenzar. Modelos gratuitos como google/gemma-4-26b-a4b-it:free funcionan para chat y visión. La generación de video/audio generalmente requiere créditos.

Instalación

Los servidores MCP se distribuyen a través de varios modelos de empaquetado. Este servidor está implementado en Node.js/TypeScript; la tabla a continuación mapea cada método del ecosistema a cómo se ejecuta aquí.

uvx vs npx: En el ecosistema MCP, npx ejecuta paquetes npm (Node) y uvx ejecuta paquetes PyPI (Python). Debido a que este servidor está basado en Node, uvx usa un lanzador de Python delgado que ejecuta npx -y @stabgan/openrouter-mcp-multimodal — aún necesitas tener Node instalado.

Un clic

Cursor
VS Code
Kiro
Claude Desktop / Windsurf / Cline	Configuración JSON manual (elige cualquier método a continuación)
Smithery	npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
Registro MCP	Página oficial del registro — paquetes npm + OCI

Pega tu OPENROUTER_API_KEY cuando se te solicite — los enlaces directos usan marcadores de posición para que los secretos nunca aparezcan en las URL.

Configuración manual

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

export OPENROUTER_API_KEY=sk-or-v1-...
uvx mcp-server-openrouter-multimodal
# pin npm version: OPENROUTER_MCP_NPM_VERSION=5.0.1 uvx mcp-server-openrouter-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "uvx",
      "args": ["mcp-server-openrouter-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

npm install -g @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "openrouter-multimodal",
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm ci && npm run build

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["/absolute/path/to/openrouter-mcp-multimodal/dist/index.js"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... stabgan/openrouter-mcp-multimodal:latest

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "stabgan/openrouter-mcp-multimodal:latest"
      ]
    }
  }
}

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
  ghcr.io/stabgan/openrouter-mcp-multimodal:5.0.1

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "ghcr.io/stabgan/openrouter-mcp-multimodal:5.0.1"
      ]
    }
  }
}

npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
# or: --client cursor | vscode | windsurf | ...

claude mcp add openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
# project scope:
claude mcp add --scope project openrouter -- npx -y @stabgan/openrouter-mcp-multimodal

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @modelcontextprotocol/inspector npx -y @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

¿Por qué este servidor?

Herramientas

19 herramientas MCP. Cada descripción incluye Usar cuando, Ejemplos buenos/malos, Falla cuando y Funciona con para que los agentes elijan la herramienta correcta y se recuperen de errores.

Los errores usan una taxonomía cerrada de _meta.code: INVALID_INPUT · UNSAFE_PATH · UPSTREAM_* · MODEL_NOT_FOUND · JOB_STILL_RUNNING · y más.

Resultados binarios de herramientas (v4.7.0+)

Las herramientas de generación (generate_image, generate_image_dedicated, generate_audio, text_to_speech, generate_video, generate_video_from_image, get_video_status) devuelven bytes de imagen, audio o video. A partir de 4.7.0 el comportamiento es explícito:

Límites en línea predeterminados (anular por tipo o globalmente):

Si antes dependías de ambos, un archivo guardado y medios en línea en el mismo resultado de herramienta, lee el archivo desde _meta.save_path (u omite save_path para obtener medios en línea cuando esté bajo el límite).

Ejemplos

Chat (modelo gratuito)

{
  "tool": "chat_completion",
  "arguments": {
    "model": "google/gemma-4-26b-a4b-it:free",
    "messages": [{ "role": "user", "content": "Summarize MCP in one sentence." }]
  }
}

Analizar una imagen

{
  "tool": "analyze_image",
  "arguments": {
    "image_path": "diagram.png",
    "question": "List every label in this diagram."
  }
}

Usa image_path y question — no image / prompt.

Buscar modelos (visión + gratuito)

{
  "tool": "search_models",
  "arguments": {
    "query": "gemma",
    "capabilities": { "vision": true },
    "limit": 10,
    "offset": 0
  }
}

Generar video (asíncrono)

{
  "tool": "generate_video",
  "arguments": {
    "model": "google/veo-3.1",
    "prompt": "Ocean waves at sunrise, cinematic drone shot",
    "duration": 4,
    "save_path": "river.mp4"
  }
}

Si el trabajo aún se está ejecutando cuando transcurre max_wait_ms, la respuesta tiene éxito con _meta.code: JOB_STILL_RUNNING y un video_id — llama a get_video_status para reanudar. Esto no es un error.

Con save_path establecido (como arriba), el resultado es un puntero de texto al archivo guardado una vez completado — no video en línea. Consulta Resultados binarios de herramientas.

Más ejemplos: docs/plans/tool-description-improvement.md

Seguridad

• Sandbox de rutas de entrada — las rutas locales en analyze_* y las imágenes de referencia deben permanecer dentro de OPENROUTER_INPUT_DIR (se recurre a OPENROUTER_OUTPUT_DIR, luego a cwd)
• Sandbox de rutas de salida — save_path debe permanecer dentro de OPENROUTER_OUTPUT_DIR
• Lecturas de trabajos asíncronos — get_chat_completion_status resuelve rutas de disco solo bajo OPENROUTER_OUTPUT_DIR/openrouter-jobs/ (4.7.0+)
• Protección SSRF — las IP privadas/reservadas están bloqueadas en las búsquedas de URL
• Contenido no confiable — los resultados de análisis se etiquetan con _meta.content_is_untrusted: true

Anula los sandboxes solo con OPENROUTER_ALLOW_UNSAFE_PATHS=1 (desaconsejado).

Reporta vulnerabilidades: SECURITY.md (divulgación privada — no publiques problemas públicos para exploits).

Configuración

Desarrollo

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm install
cp .env.example .env   # add OPENROUTER_API_KEY
npm run build

Pruebas

Las pruebas simuladas se encuentran en src/__tests__/mock/ y cubren manejadores, sandboxes de rutas, bloqueos SSRF, paginación de caché de modelos, descripciones de herramientas y salidas estructuradas — más de 330 casos adicionales más allá del conjunto principal.

npm run lint
npm run format:check
npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml

Publicación

Los artefactos publicados (npm, PyPI/uvx, Docker, GHCR) se distribuyen todos desde el mismo semver en una etiqueta git (vX.Y.Z). Hacer push a main ejecuta pruebas pero no publica en npm ni PyPI.

Flujo normal: fusiona commits convencionales a main → Release Please abre un PR de Release → fúndelo → se crea la etiqueta → CI publica en todas partes.

Flujo manual: incrementa todos los archivos de versión → npm run version:check → npm run ci + pruebas de humo → haz commit → git tag vX.Y.Z → git push origin vX.Y.Z.

Lista de verificación completa, lista de archivos, secretos de CI e instrucciones para agentes:

• docs/RELEASING.md — guía de publicación para mantenedores
• AGENTS.md — referencia rápida para agentes de IA

Solución de problemas

Los errores estructurados incluyen _meta.suggestions con próximos pasos orientados a agentes cuando estén disponibles.

Preguntas frecuentes

¿Necesito créditos de pago de OpenRouter?

No, para empezar. Los modelos gratuitos funcionan para chat y visión. La generación de audio/video generalmente requiere créditos; el análisis puede devolver 402 en algunos modelos — el servidor lo presenta como un error estructurado.

¿Qué clientes MCP son compatibles?

Cualquier cliente compatible con MCP a través de stdio: Cursor, Claude Desktop, VS Code Copilot, Windsurf, Cline, Kiro y agentes personalizados.

¿En qué se diferencia esto de llamar a OpenRouter directamente?

Este servidor añade esquemas de herramientas MCP, sandboxes de seguridad, taxonomía de errores, caché de modelos, sondeo asíncrono de video con notificaciones de progreso y descripciones de herramientas orientadas a agentes — para que los LLM invoquen la capacidad correcta sin pegamento HTTP personalizado.

¿Dónde está el aviso de seguridad para el recorrido de rutas?

Corregido en 4.5.2+ — consulta GHSA-3q7p-736f-x44v, SECURITY.md y docs/solutions/security-issues/.

Compatibilidad

Funciona con cualquier cliente MCP. Protocolo: MCP 2025-06-18. Node ≥ 22 (la imagen Docker usa Node 24).

Licencia

Apache 2.0 — consulta LICENSE.

Contribuciones

Se aceptan issues y PRs. Para cambios grandes, abre primero un issue.

Antes de enviar: ejecuta npm run ci. Usa Conventional Commits (fix:, feat:, etc.) para que Release Please pueda preparar la próxima versión. Consulta docs/RELEASING.md si necesitas publicar una versión.