OpenRouter MCP

mcp-server-open-router

Um servidor MCP (Model Context Protocol) para OpenRouter — uma chave de API, mais de 300 modelos de todos os principais laboratórios. Construído em Rust, ele expõe ferramentas de chat, visão, busca na web, listagem de modelos e saldo de créditos via stdio para que qualquer cliente MCP possa usá-las.

Modelo padrão: moonshotai/kimi-k3 — contexto de 1M, $3/$15 por M de entrada/saída, com capacidade de visão. Comunica via stdio usando JSON-RPC 2.0. Estruturalmente, espelha mcp-server-fable com a camada de requisição compatível com OpenAI de mcp-server-grok-chat.

Especificidades do OpenRouter

• Contabilidade de custo real — cada requisição de chat envia usage:{"include":true}; o rodapé da resposta mostra o USD reportado pelo OpenRouter ([cost: $0.008901]), nunca uma estimativa de constantes de preço.
• Tratamento de erro em 200 — o OpenRouter pode retornar HTTP 200 com um corpo {"error":...} de nível superior (sem choices). O servidor trata isso como um erro de ferramenta, não como um pânico ou sucesso vazio. Erros de provedor por escolha são renderizados inline.
• Raciocínio unificado — campo de requisição reasoning com esforço / excluir / habilitado; bloco opcional [reasoning]…[/reasoning] quando show_reasoning=true.
• Plugin web + Fontes — chat_with_search usa plugins:[{"id":"web"}]; páginas citadas tornam-se uma lista Sources: a partir de anotações url_citation.
• Parâmetros não suportados são descartados silenciosamente — por exemplo, kimi-k3 não suporta temperature; enviá-lo é sempre seguro.
• Cabeçalhos de atribuição — opcional app_name → X-Title, site_url → HTTP-Referer.

Ferramentas

Ferramenta	Descrição
chat	Converse com qualquer modelo do OpenRouter. Histórico de múltiplas turnas, prompt de sistema, saída estruturada via JSON schema, controle de raciocínio. Rodapé com tokens + custo real em USD.
chat_with_vision	Analisa uma imagem (URL http(s), data URL ou caminho de arquivo local). O modelo padrão aceita imagens.
chat_with_search	Chat com base na web via plugin web do OpenRouter. Retorna resposta + lista Sources:.
list_models	Catálogo filtrável com comprimento de contexto e preço $/M (cache de 5 minutos).
credits	Saldo da conta: comprado, usado, restante.

chat

Nome	Tipo	Obrigatório	Descrição
prompt	string	sim	A mensagem / prompt do usuário a ser enviado
system_prompt	string	não	Prompt de sistema opcional para definir contexto/comportamento
messages	string	não	Histórico completo da conversa como um array JSON de objetos {role, content}. Quando fornecido, prompt é anexado como a mensagem final do usuário.
model	string	não	ID do modelo (padrão: padrão configurado / moonshotai/kimi-k3). Chame list_models para navegar.
temperature	number	não	Temperatura de amostragem (0.0–2.0). Modelos que não suportam ignoram silenciosamente.
max_tokens	integer	não	Máximo de tokens a gerar
reasoning_effort	string	não	low / medium / high para modelos com capacidade de raciocínio. Oculto a menos que show_reasoning=true.
show_reasoning	boolean	não	Incluir texto de raciocínio como um bloco [reasoning] (padrão falso)
response_schema	string	não	String opcional de JSON schema para forçar saída estruturada

chat_with_vision

Nome	Tipo	Obrigatório	Descrição
prompt	string	sim	Prompt de texto descrevendo o que analisar na imagem
image	string	sim	URL http(s), data URL ou caminho de arquivo local (png/jpg/jpeg/webp/gif, máx. 20 MB)
detail	string	não	low / high / auto (padrão auto)
model	string	não	Deve ser capaz de visão; o padrão kimi-k3 aceita imagens
temperature	number	não	Temperatura de amostragem (0.0–2.0)
max_tokens	integer	não	Máximo de tokens a gerar

chat_with_search

Nome	Tipo	Obrigatório	Descrição
prompt	string	sim	A mensagem / prompt do usuário
system_prompt	string	não	Prompt de sistema opcional
model	string	não	ID do modelo (padrão: padrão configurado)
max_results	integer	não	Máximo de resultados web, 1–20 (padrão 5). ~$0.004 cada
temperature	number	não	Temperatura de amostragem (0.0–2.0)
max_tokens	integer	não	Máximo de tokens a gerar

list_models

Nome	Tipo	Obrigatório	Descrição
filter	string	não	Substring sem diferenciar maiúsculas/minúsculas sobre o ID e nome do modelo. Omita para listar todos (~344 modelos).

credits

Sem parâmetros.

Pré-requisitos

• Rust (edição 2024)
• Uma chave de API do OpenRouter de openrouter.ai/settings/keys com créditos

O servidor espera um arquivo de configuração em ~/.config/mcp-server-open-router/config.toml contendo no mínimo seu api_key. Veja config.toml.example.

api_key = "sk-or-..."

# Optional overrides:
# base_url = "https://openrouter.ai/api/v1"
# default_model = "moonshotai/kimi-k3"
# default_max_tokens = 8192
# app_name = "mcp-server-open-router"
# site_url = "https://example.com"

O servidor falha rapidamente na inicialização se a configuração estiver ausente ou api_key estiver vazio.

Compilação

cargo build --release   # produces target/release/open-router
cargo build             # debug build
cargo run               # run in dev mode
RUST_LOG=debug cargo run
cargo test              # unit tests (Display formatter, builders, mockito round-trips)

Instalação e Configuração do MCP

1. Compile o servidor

cargo build --release
# The binary will be at: target/release/open-router

Use o caminho absoluto completo para target/release/open-router em toda a configuração abaixo.

2. Instalação assistida por IA (método moderno recomendado)

Copie o bloco abaixo e cole-o diretamente no seu assistente de codificação de IA (Claude Code, Cursor, Grok, etc.). A IA cuidará da clonagem (se necessário), compilação, resolução de caminho e registro para você.

Add the mcp-server-open-router MCP server for me.

Repository: https://github.com/<your-username>/mcp-server-open-router   (update this URL if you have a fork)

Steps to perform:
1. If the repo isn't cloned locally yet, clone it and cd into it.
2. Build the release binary:
     cargo build --release
3. Determine the absolute path to the built binary (target/release/open-router).
4. Set up the config directory and file:
     mkdir -p ~/.config/mcp-server-open-router
     cp config.toml.example ~/.config/mcp-server-open-router/config.toml
   Then edit the config and add your OpenRouter API key (api_key = "sk-or-...").

5. Register it as an MCP server named "open-router".

   For Claude Code, run:
     claude mcp add open-router -- <ABSOLUTE_PATH_TO>/target/release/open-router

   For Claude Desktop or other MCP clients, add this under the "mcpServers" key (use the real absolute path):
{
  "open-router": {
    "command": "<ABSOLUTE_PATH_TO>/target/release/open-router"
  }
}

After setup, test that the `chat` and `credits` tools are available and working.

3. Configuração manual

Claude Desktop ou qualquer cliente MCP (~/.config/Claude/claude_desktop_config.json ou equivalente):

{
  "mcpServers": {
    "open-router": {
      "command": "/media/codechap/4TB/develop/mcps/mcp-server-open-router/target/release/open-router"
    }
  }
}

Claude Code (uma linha):

claude mcp add open-router -- /media/codechap/4TB/develop/mcps/mcp-server-open-router/target/release/open-router

Substitua o caminho pelo seu caminho absoluto real para o binário de release.

Uso

Uma vez registrado, um cliente MCP chama as ferramentas pelo nome.

De um cliente MCP (ex.: Claude Code)

Use a ferramenta chat do open-router. prompt: "Reply with exactly OK". max_tokens: 10

JSON-RPC bruto via stdio

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"chat",
  "arguments":{
    "prompt":"Reply with exactly OK",
    "max_tokens":10
  }}}

Toda resposta de chat bem-sucedida termina com rodapés de uso de tokens e custo real:

OK
[finish_reason: stop]
[model: moonshotai/kimi-k3 via Moonshot AI]
[tokens: 812 prompt + 431 completion = 1243 total; 640 cached; 210 reasoning]
[cost: $0.008901]

A linha de custo é o USD reportado pelo OpenRouter (porque cada requisição opta por usage.include), não uma estimativa de constantes de preço.

Estrutura do Projeto

src/
  main.rs    - entry point, config loading, stdio transport setup
  server.rs  - MCP tools (chat, chat_with_vision, chat_with_search, list_models, credits) + helpers
  api.rs     - OpenRouter HTTP client, request/response types, Display formatter
  params.rs  - tool parameter types with serde + JSON Schema derives
  config.rs  - TOML config loading

Licença

MIT