OpenRouter MCP server

Name: openrouter-mcp
Author: th3nolo

This project connects agents to OpenRouter through two front doors: an agent-first command-line interface and a strict stateless MCP server. Both use the same operation layer and stable response shapes. The MCP server exposes thirteen focused tools and one API-key usage resource.

Version 3.0 targets MCP 2026-07-28 only. Each HTTP POST is independent. The server does not accept initialize, create Mcp-Session-Id sessions, expose a GET event stream, or run a legacy fallback.

Design notes and the reasoning behind the stateless 2026-07-28 surface are in the engineering note Building a strict stateless MCP 2026-07-28 server for OpenRouter. More notes and case studies: th3nolo.com. Author: Manuel Parra.

What changed in 3.0

list_models sends pagination, filters, and sorting to OpenRouter instead of downloading the full catalog.
get_model calls OpenRouter's direct model endpoint. It replaces get_model_info; there is no alias.
list_model_endpoints returns provider price, context, uptime, latency, throughput, and supported parameters.
list_providers exposes provider geography, policy links, and service-status metadata without a browser.
list_model_rankings and list_app_rankings expose bounded versions of OpenRouter's public rankings pages.
get_credits and list_activity expose account data with a separate management-key boundary.
get_analytics_schema and query_analytics expose the current Activity Explore analytics contract with explicit time ranges and bounded results.
chat_with_model and compare_models return a generation_id and the resolved model.
get_generation uses that ID to fetch exact provider, token, latency, and cost metadata.
The openrouter-mcp CLI exposes the same operations directly, emits JSON automatically when piped, and never prompts.
Browser inspection informed the surface contract, but no browser, cookie, HAR file, or browser session is required at runtime.
openrouter://models and openrouter://pricing were removed. Their unbounded catalog payloads are not retained as fallbacks.
Unknown fields added by OpenRouter are stripped at the API boundary. The MCP output schemas remain stable.
Static discovery responses declare a one-hour public cache hint. API-key usage remains private with a five-second hint.
Model comparisons run at most three OpenRouter calls at once. Paid calls are never retried automatically.
Custom OpenRouter base URLs must use HTTPS. Plain HTTP is accepted only for loopback development.

See docs/API.md for the complete tool contract, docs/CLI.md for direct CLI use, and docs/MCP-2026-07-28.md for wire-level behavior.

Requirements

Node.js 24 LTS
pnpm 12.0.0, exactly as pinned in package.json
An OpenRouter API key for rankings, inference, generation metadata, and key-usage data
An OpenRouter management key for credit totals, account activity, and analytics

OpenRouter currently serves public model and provider discovery without a key. That anonymous behavior may be rate-limited or changed upstream.

Install

git clone https://github.com/th3nolo/openrouter-mcp.git
cd openrouter-mcp
pnpm install
pnpm run check

pnpm-workspace.yaml waits 72 hours before resolving a release. It also blocks exotic transitive sources and trust downgrades. Only [email protected] may run a dependency lifecycle script.

On Windows, [email protected] does not carry an Authenticode signature. Windows may label it "Unknown publisher." Install it with a method from pnpm's installation guide, and do not weaken Defender or PowerShell execution policy to suppress the warning.

Copy .env.example to .env, then set:

OPENROUTER_API_KEY=your_openrouter_api_key_here
# Optional; required only for get_credits and list_activity
OPENROUTER_MANAGEMENT_KEY=your_openrouter_management_key_here

Keep .env out of Git.

Use the CLI

Build once, then call the same operations without starting an MCP client:

pnpm run build
node dist/cli.js schema
node dist/cli.js models list --q claude --limit 5
node dist/cli.js providers list --datacenter DE
node dist/cli.js rankings models --limit 10
node dist/cli.js account credits
node dist/cli.js analytics schema

Interactive terminals receive compact text or tables. Redirected output is JSON automatically; --json makes that behavior explicit. Diagnostics use stderr, usage failures exit with status 2, operation failures exit with status 1, and commands never prompt. Run the strict stateless server through the same binary with node dist/cli.js serve --transport stdio.

Use with Claude over stdio

stdio is the default transport for local Claude integrations.

pnpm run build
claude mcp add --transport stdio --scope user \
  --env OPENROUTER_API_KEY=your_openrouter_api_key_here \
  openrouter -- node /absolute/path/to/openrouter-mcp/dist/server.js

The equivalent Claude Desktop configuration is in examples/claude-config.json.

Use with Claude over local HTTP

Start the loopback-only server:

pnpm run build
OPENROUTER_API_KEY=your_openrouter_api_key_here pnpm run start:http

On PowerShell:

$env:OPENROUTER_API_KEY = "your_openrouter_api_key_here"
pnpm run start:http

Then register its URL:

claude mcp add --transport http --scope user openrouter http://127.0.0.1:3000/mcp

HTTP mode listens only on 127.0.0.1 and validates the Host and Origin headers. It does not implement a bearer-token shortcut.

Do not expose this listener directly to the internet. Put an HTTPS gateway that implements the MCP OAuth 2.1 resource-server flow in front of it.

Tools

Tool	Purpose	External effect
`list_models`	Search, filter, sort, and page the live model catalog	Read-only OpenRouter request
`get_model`	Read one exact model, variant, or alias	Read-only OpenRouter request
`list_model_endpoints`	Compare the providers serving one model	Read-only OpenRouter request
`list_providers`	Filter providers by name, headquarters, or datacenter	Read-only public request
`list_model_rankings`	Read one completed UTC day of model rankings	Read-only API-key request
`list_app_rankings`	Read popular or trending public apps	Read-only API-key request
`get_credits`	Read purchased, used, and remaining credits	Read-only management request
`list_activity`	Read endpoint-level daily account activity	Read-only management request
`get_analytics_schema`	Discover current analytics metrics, dimensions, operators, and granularities	Read-only management request
`query_analytics`	Query bounded Activity Explore aggregates over an explicit time range	Read-only management request
`chat_with_model`	Generate one response and return its generation ID	Can consume API credits
`compare_models`	Generate with two to eight models, three calls at a time	Can consume API credits per model
`get_generation`	Read provider, tokens, latency, and cost for one generation ID	Read-only authenticated request

Each tool returns a text block and structuredContent. Zod rejects invalid input before the handler runs. The SDK converts upstream failures into MCP tool errors.

Resource

URI	Data	Cache hint
`openrouter://usage`	Usage and limits for the configured API key	Private, five seconds

Model and pricing catalogs are tools rather than resources so every response can be filtered and bounded.

Verify the live API

pnpm run test:live

The command always checks live model pagination, direct model lookup, model endpoints, and provider discovery. If OPENROUTER_API_KEY is configured, it also checks both ranking datasets, sends one short request through openrouter/free, and resolves the returned generation metadata. If OPENROUTER_MANAGEMENT_KEY is configured, it checks credits, bounded activity, analytics schema discovery, and a small seven-day analytics query. The report never prints a credential or generation ID.

Environment

Variable	Default	Meaning
`OPENROUTER_API_KEY`	none	OpenRouter key for rankings, inference, generation metadata, and `openrouter://usage`
`OPENROUTER_MANAGEMENT_KEY`	`OPENROUTER_API_KEY`	OpenRouter management key for credits, account activity, and analytics
`OPENROUTER_BASE_URL`	`https://openrouter.ai/api/v1`	HTTPS OpenRouter API base URL; HTTP is loopback-only
`OPENROUTER_SITE_URL`	none	Optional `HTTP-Referer` app attribution
`OPENROUTER_APP_NAME`	`OpenRouter MCP Server`	`X-OpenRouter-Title` attribution
`OPENROUTER_TIMEOUT_MS`	`60000`	Per-request timeout
`MCP_TRANSPORT`	`stdio`	`stdio` or `http`
`MCP_HTTP_PORT`	`3000`	Local HTTP port

Command-line --transport and --port values override their environment variables.

Development

pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build

# Complete offline source gate
pnpm run check

# Build first, then verify the packed distribution
pnpm pack --out contract-package.tgz
pnpm run test:smoke

The deterministic tests cover modern HTTP without initialize, strict legacy rejection, real stdio negotiation, CLI schema output, cache hints, credential separation, upstream and local pagination, direct API routes, generation handles, comparison concurrency, cancellation, schema drift, bounded errors, and HTTPS enforcement. The live contract tests are separate because they depend on current network and OpenRouter availability. pnpm run test:live:public runs the public catalog regression; pnpm run test:live runs the broader live contract described above. Missing credentials remain reported as skipped by the live report, never as passed. Neither live command runs in application CI.

.github/workflows/application.yml runs pnpm run check and the packed-distribution smoke test on pushes and pull requests with Node 24.19.0, pnpm 12.0.0, immutable action references, and a frozen lockfile. GitHub default-setup CodeQL remains a separate security check. The repository has no configured formatter; CI checks whitespace and the existing ESLint rules.

The offline runner refuses a checkout containing .env, removes inherited OpenRouter settings, and preloads a network-denial guard in the tests and their stdio children. Setting OPENROUTER_LIVE_TEST no longer enables live requests in pnpm test. The packed smoke suite extracts the actual tarball and uses its declared CLI/server entrypoints with the real SDK client; it checks modern discovery, strict legacy rejection, invalid tool/CLI input, stdout framing, EOF and process shutdown. Dependencies resolve from the frozen checkout, so this is packaged-entrypoint evidence, not a clean consumer install or live OpenRouter acceptance. TAP output reports test/pass/fail/skip counts separately for each offline suite.

Sources

License

MIT