OpenRouter MCP

mcp-server-open-router

Un servidor MCP (Model Context Protocol) para OpenRouter — una clave de API, más de 300 modelos de cada laboratorio importante. Construido en Rust, expone herramientas de chat, visión, búsqueda web, listado de modelos y saldo de créditos a través de stdio para que cualquier cliente MCP pueda usarlas.

Modelo por defecto: moonshotai/kimi-k3 — contexto de 1M, $3/$15 por M de entrada/salida, con capacidad de visión. Se comunica mediante stdio usando JSON-RPC 2.0. Estructuralmente refleja mcp-server-fable con la capa de solicitudes compatible con OpenAI de mcp-server-grok-chat.

Particularidades de OpenRouter

• Contabilidad de coste real — cada solicitud de chat envía usage:{"include":true}; el pie de respuesta muestra el USD reportado por OpenRouter ([cost: $0.008901]), nunca una estimación de constantes de precios.
• Manejo de error en 200 — OpenRouter puede devolver HTTP 200 con un cuerpo de nivel superior {"error":...} (sin choices). El servidor lo trata como un error de herramienta, no como un pánico o un éxito vacío. Los errores de proveedor por elección se muestran en línea.
• Razonamiento unificado — campo de solicitud reasoning con effort / exclude / enabled; bloque opcional [reasoning]…[/reasoning] cuando show_reasoning=true.
• Plugin web + Fuentes — chat_with_search usa plugins:[{"id":"web"}]; las páginas citadas se convierten en una lista Sources: a partir de anotaciones url_citation.
• Los parámetros no soportados se descartan silenciosamente — p. ej., kimi-k3 no soporta temperature; enviarlo siempre es seguro.
• Cabeceras de atribución — opcional app_name → X-Title, site_url → HTTP-Referer.

Herramientas

Herramienta	Descripción
chat	Chatea con cualquier modelo de OpenRouter. Historial de múltiples turnos, prompt de sistema, salida estructurada mediante esquema JSON, control de razonamiento. Pie con tokens + coste real en USD.
chat_with_vision	Analiza una imagen (URL http(s), data URL o ruta de archivo local). El modelo por defecto acepta imágenes.
chat_with_search	Chat con base web mediante el plugin web de OpenRouter. Devuelve respuesta + lista Sources:.
list_models	Catálogo filtrable con longitud de contexto y precios $/M (caché de 5 minutos).
credits	Saldo de cuenta: comprado, usado, restante.

chat

Nombre	Tipo	Requerido	Descripción
prompt	string	sí	El mensaje / prompt del usuario a enviar
system_prompt	string	no	Prompt de sistema opcional para establecer contexto/comportamiento
messages	string	no	Historial completo de conversación como un array JSON de objetos {role, content}. Cuando se proporciona, prompt se añade como mensaje final del usuario.
model	string	no	ID del modelo (por defecto: el configurado / moonshotai/kimi-k3). Llama a list_models para explorar.
temperature	number	no	Temperatura de muestreo (0.0–2.0). Los modelos que no la soportan la ignoran silenciosamente.
max_tokens	integer	no	Máximo de tokens a generar
reasoning_effort	string	no	low / medium / high para modelos con capacidad de razonamiento. Oculto a menos que show_reasoning=true.
show_reasoning	boolean	no	Incluir texto de razonamiento como un bloque [reasoning] (por defecto false)
response_schema	string	no	Cadena de esquema JSON opcional para forzar salida estructurada

chat_with_vision

Nombre	Tipo	Requerido	Descripción
prompt	string	sí	Prompt de texto que describe qué analizar en la imagen
image	string	sí	URL http(s), data URL o ruta de archivo local (png/jpg/jpeg/webp/gif, máx. 20 MB)
detail	string	no	low / high / auto (por defecto auto)
model	string	no	Debe ser capaz de visión; el kimi-k3 por defecto acepta imágenes
temperature	number	no	Temperatura de muestreo (0.0–2.0)
max_tokens	integer	no	Máximo de tokens a generar

chat_with_search

Nombre	Tipo	Requerido	Descripción
prompt	string	sí	El mensaje / prompt del usuario
system_prompt	string	no	Prompt de sistema opcional
model	string	no	ID del modelo (por defecto: el configurado)
max_results	integer	no	Máximo de resultados web, 1–20 (por defecto 5). ~$0.004 cada uno
temperature	number	no	Temperatura de muestreo (0.0–2.0)
max_tokens	integer	no	Máximo de tokens a generar

list_models

Nombre	Tipo	Requerido	Descripción
filter	string	no	Subcadena sin distinción de mayúsculas sobre el id y nombre del modelo. Omítelo para listar todos (~344 modelos).

credits

Sin parámetros.

Requisitos previos

• Rust (edition 2024)
• Una clave de API de OpenRouter desde openrouter.ai/settings/keys con créditos

El servidor espera un archivo de configuración en ~/.config/mcp-server-open-router/config.toml que contenga como mínimo tu api_key. Consulta 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"

El servidor falla rápidamente al inicio si falta la configuración o api_key está vacío.

Compilación

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)

Instalación y configuración de MCP

1. Compilar el servidor

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

Usa la ruta absoluta completa a target/release/open-router en toda la configuración siguiente.

2. Instalación asistida por IA (método moderno recomendado)

Copia el bloque siguiente y pégalo directamente en tu asistente de codificación con IA (Claude Code, Cursor, Grok, etc.). La IA se encargará de clonar (si es necesario), compilar, resolver rutas y registrarlo por ti.

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. Configuración manual

Claude Desktop o cualquier cliente MCP (~/.config/Claude/claude_desktop_config.json o equivalente):

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

Claude Code (una línea):

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

Reemplaza la ruta con tu ruta absoluta real al binario de la versión.

Uso

Una vez registrado, un cliente MCP llama a las herramientas por su nombre.

Desde un cliente MCP (p. ej., Claude Code)

Usa la herramienta chat de open-router. prompt: "Reply with exactly OK". max_tokens: 10

JSON-RPC crudo sobre stdio

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

Cada respuesta de chat exitosa termina con pies de uso de tokens y coste 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]

La línea de coste es el USD reportado por OpenRouter (porque cada solicitud opta por usage.include), no una estimación de constantes de precios.

Estructura del proyecto

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

Licencia

MIT