OpenRouter MCP Server

Remote-MCP-Server (streamable HTTP, zustandsloses JSON), der es KI-Agenten ermöglicht, Aufgaben an günstigere Modelle zu delegieren über die OpenRouter-API, den Katalog und Live-Preise abzufragen, mit einer über eine .env-Datei konfigurierbaren Kostenrichtlinie.

Was es tut

• Live-Katalog: fragt OpenRouters GET /api/v1/models ab (mit einem 5-Minuten-Cache) und stellt Preise in USD pro Million Tokens, Kontextfenster und Tool-Calling-Unterstützung bereit.

• Explizite Delegation: Der Agent wählt das Modell anhand der Preise aus und delegiert die Aufgabe.

• Automatische preisbasierte Delegation: Der Server wählt das Modell basierend auf einer Stufe (economy / balanced / quality) anhand konfigurierbarer Preisbänder aus.

• Richtlinie über .env: maximale Preisobergrenzen, erlaubte/blockierte Modelllisten, Standardmodell, bevorzugte Anbieter.

• Echte Kosten: Jede Delegation gibt verwendete Tokens und geschätzte Kosten in USD zurück.

Related MCP server: frugal

Installation

npm install
cp .env.example .env   # edit and set your OPENROUTER_API_KEY
npm run build
npm start              # listens on http://localhost:3000/mcp

Für die Entwicklung mit Auto-Reload: npm run dev.

Docker

Ein Multi-Arch-Image (linux/amd64, linux/arm64) wird automatisch von GitHub Actions erstellt und auf GHCR veröffentlicht:

ghcr.io/vmhq/openrouter-mcp-server

Verfügbare Tags: latest (main branch), vX.Y.Z / X.Y (Releases), main und sha-<commit>.

Docker Compose

services:
  openrouter-mcp:
    image: ghcr.io/vmhq/openrouter-mcp-server:latest
    container_name: openrouter-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file:
      - .env
    volumes:
      # Persists OAuth state (registered clients, token hashes)
      - ./data:/app/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

docker compose up -d

Hinweis: Der Container läuft als unprivilegierter node-Benutzer. Stellen Sie sicher, dass das gemountete ./data-Verzeichnis für UID 1000 beschreibbar ist (chown -R 1000:1000 ./data), andernfalls kann der OAuth-Zustand nicht gespeichert werden.

Beispiel .env

# --- Required ---
# Your OpenRouter API key (https://openrouter.ai/keys)
OPENROUTER_API_KEY=sk-or-v1-...

# --- HTTP server ---
# Port where the MCP endpoint is exposed (http://host:PORT/mcp)
PORT=3000
# Optional static bearer token. If set, MCP clients must send
# "Authorization: Bearer <token>". Strongly recommended if the server
# is reachable outside localhost.
MCP_AUTH_TOKEN=

# --- Interactive OAuth with PocketID (for AI agents like Claude) ---
# Public URL of this server (e.g. https://mcp.example.com). Required so the
# OAuth metadata and callback point to the right URL behind a reverse proxy.
MCP_PUBLIC_URL=
# When all three POCKETID_* variables are set, the /oauth/authorize flow
# delegates the human login to your PocketID instance (passkey).
# In PocketID: create an OIDC client and register this callback:
#   <MCP_PUBLIC_URL>/oauth/callback
POCKETID_ISSUER=
POCKETID_CLIENT_ID=
POCKETID_CLIENT_SECRET=
# Optional OIDC scopes (space-separated). Default: "openid profile email".
# POCKETID_SCOPES=openid profile email
# Path of the file where OAuth state is persisted (registered clients,
# one-time codes, and token hashes). Default: ./data/oauth-state.json
# MCP_OAUTH_STATE_PATH=./data/oauth-state.json
# OAuth access token lifetime, in seconds. Default: 2592000 (30 days).
# MCP_OAUTH_TOKEN_TTL_S=2592000

# --- Optional OpenRouter attribution (rankings) ---
APP_URL=
APP_TITLE=OpenRouter MCP Server

# --- Delegation policy ---
# Default model when the agent doesn't specify one in openrouter_delegate_task
DEFAULT_MODEL=

# Price caps (USD per million tokens). Models above them are rejected
# with an explanatory error. Empty = no limit.
MAX_PROMPT_PRICE_PER_M=
MAX_COMPLETION_PRICE_PER_M=

# Comma-separated control lists. Accept exact ids ("openai/gpt-4.1-mini")
# or provider prefixes ("openai/"). Empty ALLOWED_MODELS = all allowed
# (except blocked ones).
ALLOWED_MODELS=
BLOCKED_MODELS=

# Allow free models (price 0)? They usually have strict rate limits.
ALLOW_FREE_MODELS=true

# Preferred providers for automatic selection (openrouter_auto_delegate)
PREFERRED_PROVIDERS=openai,anthropic,google,meta-llama,mistralai,deepseek,qwen,x-ai,amazon

# "Combined" price caps (70% prompt + 30% completion, USD/M tokens)
# for each tier of the automatic selection.
TIER_ECONOMY_MAX_PRICE=0.5
TIER_BALANCED_MAX_PRICE=3
TIER_QUALITY_MAX_PRICE=15

# Model catalog cache, in seconds
MODELS_CACHE_TTL_SECONDS=300

Umgebungsvariablen

Siehe .env.example — die wichtigsten:

Bereitgestellte Tools

Typischer Agentenablauf: openrouter_list_models (oder direkt openrouter_auto_delegate mit der economy-Stufe) → Aufgabe delegieren → Antwort verwenden, mit dem Wissen, wie viel es gekostet hat.

Wichtig: Das delegierte Modell sieht die Unterhaltung des Agenten nicht; die Aufgabe (task) muss in sich geschlossen sein, mit dem gesamten notwendigen Kontext.

Verbinden eines Agenten

Claude Code:

claude mcp add --transport http openrouter http://localhost:3000/mcp

Mit einem Auth-Token:

claude mcp add --transport http openrouter http://YOUR_HOST:3000/mcp --header "Authorization: Bearer YOUR_TOKEN"

Beliebiger MCP-Client: Richten Sie ihn auf den POST /mcp-Endpunkt mit dem „streamable HTTP“-Transport. Es gibt einen GET /health-Endpunkt für die Überwachung.

claude.ai (Remote-Connector): erfordert eine öffentliche HTTPS-URL — stellen Sie den Server auf einem VPS hinter einem Reverse-Proxy (Caddy/nginx) bereit oder verwenden Sie einen Tunnel (z. B. cloudflared tunnel). Mit aktiviertem OAuth (siehe unten) fügen Sie den Connector hinzu, der auf https://YOUR_HOST/mcp zeigt, und lassen die erweiterten OAuth-Client-ID/Secret-Felder leer: Der Server veröffentlicht OAuth-Metadaten und unterstützt Dynamic Client Registration, sodass Claude sich selbst registriert und sein Token automatisch erhält, wenn Sie auf Autorisieren klicken.

OAuth mit PocketID

Der Server implementiert vollständiges OAuth 2.1 für KI-Agenten (Claude, Cursor, …): Er fungiert als Autorisierungsserver gegenüber MCP-Clients (RFC 7591 Dynamic Client Registration + PKCE S256 + Ausstellung eigener Tokens, mit RFC 8414/9728-Metadaten) und delegiert den menschlichen Login an Ihre PocketID-Instanz über OIDC (Passkey).

Ablauf: Der MCP-Client erhält eine 401 mit WWW-Authenticate → entdeckt die Metadaten unter /.well-known/oauth-protected-resource → registriert sich unter /oauth/register → öffnet /oauth/authorize im Browser → der Benutzer meldet sich bei PocketID mit seinem Passkey an → PocketID kehrt zu /oauth/callback zurück → der Server stellt seinen eigenen Code aus und der Client tauscht ihn unter /oauth/token gegen ein Zugriffstoken (standardmäßig 30 Tage) ein.

Einrichtung:

1. Erstellen Sie in PocketID einen neuen OIDC-Client.

2. Registrieren Sie den Callback: <MCP_PUBLIC_URL>/oauth/callback.

3. Beschränken Sie, wer sich anmelden kann, mithilfe der erlaubten Gruppen des OIDC-Clients in PocketID.

4. Kopieren Sie Client-ID und Client-Secret in POCKETID_CLIENT_ID / POCKETID_CLIENT_SECRET und setzen Sie die PocketID-Basis-URL in POCKETID_ISSUER.

5. Setzen Sie MCP_PUBLIC_URL auf die öffentliche HTTPS-URL des Servers.

Wenn die POCKETID_*-Variablen nicht gesetzt sind, zeigt der interaktive /oauth/authorize-Ablauf einen Fehler; das statische MCP_AUTH_TOKEN-Bearer funktioniert parallel weiterhin für Maschine-zu-Maschine-Zugriff (curl, Codex usw.).

Der OAuth-Zustand (registrierte Clients, Einmalcodes und SHA-256-Hashes der Tokens — niemals die Klartext-Tokens) wird in ./data/oauth-state.json gespeichert (konfigurierbar über MCP_OAUTH_STATE_PATH). Wenn der Connector nach einem Neustart mit gelöschtem Zustand fehlschlägt, entfernen Sie ihn in Claude und fügen Sie ihn erneut hinzu, damit er sich neu registriert.

Wie openrouter_auto_delegate ein Modell auswählt

1. Filtert den Katalog nach der .env-Richtlinie und den Anforderungen des Aufrufs (require_tools, min_context, Textausgabe).

2. Berechnet den kombinierten Preis pro Modell: 0.7·input_price + 0.3·output_price (USD/M Tokens).

3. Je nach Stufe sucht es innerhalb seines Preisbands (fällt bei Leere auf das benachbarte Band zurück):

   • economy (standardmäßig ≤ 0,5 $/M): das günstigste.

   • balanced (0,5–3 $/M): das günstigste im mittleren Band.

   • quality (3–15 $/M): das höchstpreisige innerhalb der Obergrenze (Preis als Näherung für Fähigkeiten, ohne Flaggschiff-Modelle zu erreichen).

4. Bevorzugt Anbieter aus PREFERRED_PROVIDERS und meldet in der Antwort das gewählte Modell, die Begründung und die verworfenen Alternativen.

Sicherheit

• Der OpenRouter-API-Schlüssel befindet sich nur in der .env des Servers; er wird niemals an Agenten weitergegeben.

• Die .env-Datei befindet sich in .gitignore.

• Wenn der Port von außen erreichbar ist, setzen Sie MCP_AUTH_TOKEN und stellen Sie den Dienst hinter HTTPS bereit.