openrouter-mcp-multimodal

OpenRouter MCP Multimodal

O servidor MCP para agentes de IA multimodais.
Uma instalação · 19 ferramentas · 300+ modelos OpenRouter · texto, visão, áudio & vídeo — análise e geração.

Início rápido · Ferramentas · Exemplos · Segurança · Solução de problemas · Desenvolvimento · Lançamento · Perguntas frequentes

O que é isto?

OpenRouter MCP Multimodal é um servidor Model Context Protocol (MCP) de nível de produção — listado no registro oficial de MCP como io.github.stabgan/openrouter-multimodal. Ele conecta agentes de codificação de IA (Cursor, Claude Desktop, VS Code, Windsurf, Cline e outros) à API unificada de LLM do OpenRouter via stdio.

Ao contrário de servidores MCP somente texto, uma única instalação cobre a superfície multimodal completa:

Robustez de produção: sandboxes de caminhos de entrada/saída (incluindo arquivos locais analyze_* a partir da v4.5.2), proteções SSRF, erros estruturados com _meta.code, saídas estruturadas MCP 2025-06-18, ícones de ferramentas (2025-11-25), notificações assíncronas de progresso de vídeo e 1000+ testes automatizados (unitários, mock, regressão e integração ao vivo).

Início rápido

1. Obtenha uma chave de API (o nível gratuito funciona) → openrouter.ai/keys

2. Execute o servidor

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

3. Adicione ao seu cliente MCP — copie um bloco JSON de Instalação para a configuração do seu cliente:

Use o objeto mcpServers de Configuração manual abaixo.

Nenhum crédito necessário para começar. Modelos gratuitos como google/gemma-4-26b-a4b-it:free funcionam para chat e visão. A geração de vídeo/áudio normalmente exige créditos.

Instalação

Os servidores MCP são distribuídos por vários modelos de empacotamento. Este servidor é implementado em Node.js/TypeScript; a tabela abaixo mapeia cada método do ecossistema para como executá-lo aqui.

uvx vs npx: No ecossistema MCP, npx executa pacotes npm (Node) e uvx executa pacotes PyPI (Python). Como este servidor é baseado em Node, uvx usa um launcher Python fino que executa npx -y @stabgan/openrouter-mcp-multimodal — você ainda precisa ter o Node instalado.

Um clique

Cursor
VS Code
Kiro
Claude Desktop / Windsurf / Cline	Configuração JSON manual (escolha qualquer método abaixo)
Smithery	npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
Registro MCP	Página oficial do registro — pacotes npm + OCI

Cole seu OPENROUTER_API_KEY quando solicitado — os deeplinks usam espaços reservados para que segredos nunca apareçam em URLs.

Configuração 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 que este servidor?

Ferramentas

19 ferramentas MCP. Cada descrição inclui Use quando, Exemplos bons/ruins, Falha quando e Funciona com para que agentes escolham a ferramenta certa e se recuperem de erros.

Erros usam uma taxonomia fechada _meta.code: INVALID_INPUT · UNSAFE_PATH · UPSTREAM_* · MODEL_NOT_FOUND · JOB_STILL_RUNNING · e mais.

Resultados binários de ferramentas (v4.7.0+)

Ferramentas de geração (generate_image, generate_image_dedicated, generate_audio, text_to_speech, generate_video, generate_video_from_image, get_video_status) retornam bytes de imagem, áudio ou vídeo. A partir de 4.7.0 o comportamento é explícito:

Tetos inline padrão (substitua por tipo ou globalmente):

Se você dependia anteriormente de ambos um arquivo salvo e mídia inline no mesmo resultado de ferramenta, leia o arquivo de _meta.save_path (ou omita save_path para obter mídia inline quando abaixo do teto).

Exemplos

Chat (modelo gratuito)

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

Analisar uma imagem

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

Use image_path e question — não image / prompt.

Buscar modelos (visão + gratuito)

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

Gerar vídeo (assíncrono)

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

Se o trabalho ainda estiver em execução quando max_wait_ms expirar, a resposta é bem-sucedida com _meta.code: JOB_STILL_RUNNING e um video_id — chame get_video_status para retomar. Isso não é um erro.

Com save_path definido (como acima), o resultado é um ponteiro de texto para o arquivo salvo quando concluído — não vídeo inline. Veja Resultados binários de ferramentas.

Mais exemplos: docs/plans/tool-description-improvement.md

Segurança

• Sandbox de caminho de entrada — caminhos locais em analyze_* e imagens de referência devem permanecer dentro de OPENROUTER_INPUT_DIR (recai para OPENROUTER_OUTPUT_DIR, depois cwd)
• Sandbox de caminho de saída — save_path deve permanecer dentro de OPENROUTER_OUTPUT_DIR
• Leituras de trabalhos assíncronos — get_chat_completion_status resolve caminhos de disco somente sob OPENROUTER_OUTPUT_DIR/openrouter-jobs/ (4.7.0+)
• Proteção SSRF — IPs privados/reservados bloqueados em buscas de URL
• Conteúdo não confiável — saídas de análise marcadas _meta.content_is_untrusted: true

Substitua sandboxes somente com OPENROUTER_ALLOW_UNSAFE_PATHS=1 (desencorajado).

Reporte vulnerabilidades: SECURITY.md (divulgação privada — não abra issues públicas para exploits).

Configuração

Desenvolvimento

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

Testes

Os testes simulados ficam em src/__tests__/mock/ e cobrem handlers, sandboxes de caminho, bloqueios de SSRF, paginação de cache de modelos, descrições de ferramentas e saídas estruturadas — mais de 330 casos adicionais além do conjunto principal.

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

Lançamento

Os artefatos publicados (npm, PyPI/uvx, Docker, GHCR) são todos enviados a partir do mesmo semver em uma tag git (vX.Y.Z). Enviar para main executa os testes, mas não publica no npm ou PyPI.

Fluxo normal: mescle commits convencionais para main → o Release Please abre um PR de lançamento → mescle-o → a tag é criada → o CI publica em todos os lugares.

Fluxo manual: atualize todos os arquivos de versão → npm run version:check → npm run ci + testes de fumaça → commit → git tag vX.Y.Z → git push origin vX.Y.Z.

Lista de verificação completa, lista de arquivos, segredos de CI e instruções para agentes:

• docs/RELEASING.md — guia de lançamento para mantenedores
• AGENTS.md — referência rápida para agentes de IA

Solução de problemas

Erros estruturados incluem _meta.suggestions com próximos passos orientados a agentes quando disponíveis.

Perguntas frequentes

Preciso de créditos pagos do OpenRouter?

Não, para começar. Modelos gratuitos funcionam para chat e visão. A geração de áudio/vídeo geralmente exige créditos; a análise pode retornar 402 em alguns modelos — o servidor apresenta isso como um erro estruturado.

Quais clientes MCP são suportados?

Qualquer cliente compatível com MCP via stdio: Cursor, Claude Desktop, VS Code Copilot, Windsurf, Cline, Kiro e agentes personalizados.

Como isso é diferente de chamar o OpenRouter diretamente?

Este servidor adiciona esquemas de ferramentas MCP, sandboxes de segurança, taxonomia de erros, cache de modelos, polling assíncrono de vídeo com notificações de progresso e descrições de ferramentas orientadas a agentes — para que LLMs invoquem a capacidade certa sem código HTTP personalizado.

Onde está o aviso de segurança para travessia de caminho?

Corrigido na 4.5.2+ — veja GHSA-3q7p-736f-x44v, SECURITY.md e docs/solutions/security-issues/.

Compatibilidade

Funciona com qualquer cliente MCP. Protocolo: MCP 2025-06-18. Node ≥ 22 (a imagem Docker usa Node 24).

Licença

Apache 2.0 — veja LICENSE.

Contribuição

Issues e PRs são bem-vindos. Para mudanças grandes, abra uma issue primeiro.

Antes de enviar: execute npm run ci. Use Conventional Commits (fix:, feat:, etc.) para que o Release Please possa cortar o próximo lançamento. Veja docs/RELEASING.md se precisar enviar uma versão.