OpenRouter MCP Server
Based on the provided schema, this server lets you discover OpenRouter models and run model inference/comparison through four tools.
list_models: list available OpenRouter models.chat_with_model: send a message to a specific model, with optional system prompt, max tokens, and temperature; this can consume API credits.compare_models: send the same message to multiple models and compare their responses; this can consume API credits per model.get_model_info: retrieve detailed information about a specific model.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenRouter MCP Server compare responses from GPT-4 and Claude-3 about the future of AI"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenRouter MCP server
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_modelssends pagination, filters, and sorting to OpenRouter instead of downloading the full catalog.get_modelcalls OpenRouter's direct model endpoint. It replacesget_model_info; there is no alias.list_model_endpointsreturns provider price, context, uptime, latency, throughput, and supported parameters.list_providersexposes provider geography, policy links, and service-status metadata without a browser.list_model_rankingsandlist_app_rankingsexpose bounded versions of OpenRouter's public rankings pages.get_creditsandlist_activityexpose account data with a separate management-key boundary.get_analytics_schemaandquery_analyticsexpose the current Activity Explore analytics contract with explicit time ranges and bounded results.chat_with_modelandcompare_modelsreturn ageneration_idand the resolved model.get_generationuses that ID to fetch exact provider, token, latency, and cost metadata.The
openrouter-mcpCLI 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://modelsandopenrouter://pricingwere 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, docs/MCP-2026-07-28.md for wire-level behavior, and docs/DESIGN.md for the design decisions and their reasons.
Related MCP server: OpenRouter MCP Multimodal Server
Requirements
Node.js 24 LTS
pnpm 12.0.0, exactly as pinned in
package.jsonAn 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 checkThe project uses pnpm only. package.json declares devEngines.packageManager as pnpm@12.0.0 with onFail: "error", so npm install, npm ci and npm run stop with EBADDEVENGINES.
pnpm-workspace.yaml waits 72 hours before resolving a release. It also blocks exotic transitive sources and trust downgrades. Only esbuild@0.28.2 may run a dependency lifecycle script.
On Windows, pnpm@12.0.0 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_hereKeep .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 schemaInteractive 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.jsThe 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:httpOn PowerShell:
$env:OPENROUTER_API_KEY = "your_openrouter_api_key_here"
pnpm run start:httpThen register its URL:
claude mcp add --transport http --scope user openrouter http://127.0.0.1:3000/mcpHTTP 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 |
| Search, filter, sort, and page the live model catalog | Read-only OpenRouter request |
| Read one exact model, variant, or alias | Read-only OpenRouter request |
| Compare the providers serving one model | Read-only OpenRouter request |
| Filter providers by name, headquarters, or datacenter | Read-only public request |
| Read one completed UTC day of model rankings | Read-only API-key request |
| Read popular or trending public apps | Read-only API-key request |
| Read purchased, used, and remaining credits | Read-only management request |
| Read endpoint-level daily account activity | Read-only management request |
| Discover current analytics metrics, dimensions, operators, and granularities | Read-only management request |
| Query bounded Activity Explore aggregates over an explicit time range | Read-only management request |
| Generate one response and return its generation ID | Can consume API credits |
| Generate with two to eight models, three calls at a time | Can consume API credits per model |
| 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 |
| 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:liveThe 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 |
| none | OpenRouter key for rankings, inference, generation metadata, and |
|
| OpenRouter management key for credits, account activity, and analytics |
|
| HTTPS OpenRouter API base URL; HTTP is loopback-only |
| none | Optional |
|
|
|
|
| Per-request timeout |
|
|
|
|
| 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:smokeThe deterministic tests cover modern HTTP without initialize, strict legacy rejection, real stdio negotiation, the real loopback HTTP server (routing, Host and Origin checks, shutdown), 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/workflows/secret-scan.yml runs gitleaks 8.30.1 (checksum-pinned) over the full Git history on every push and pull request. 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 guard in the tests and their children that allows only 127.0.0.1 and ::1. 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 over stdio and loopback HTTP, 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. See docs/TESTING.md for the test layout and rules.
Sources
License
MIT
Available Tools
4 toolschat_with_modelB
Send a message to a specific OpenRouter model
Inputs: model (required), message (required), max_tokens, temperature, +1 more.
compare_modelsC
Compare responses from multiple models
Inputs: models (required), message (required), max_tokens.
get_model_infoC
Get detailed information about a specific model
Inputs: model (required).
list_modelsB
Get list of available OpenRouter models
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: chat_with_model is for sending messages, compare_models is for comparing multiple models, get_model_info is for retrieving details about a specific model, and list_models is for listing available models. There is no overlap or ambiguity between these functions.
All tool names follow a consistent verb_noun pattern (e.g., chat_with_model, compare_models, get_model_info, list_models). The naming is uniform and predictable throughout the set.
With 4 tools, the server is well-scoped for interacting with OpenRouter models. Each tool serves a distinct and necessary function, and the count is appropriate for the domain without being too sparse or bloated.
The tool set covers core operations for model interaction: listing, getting info, chatting, and comparing. A minor gap is the lack of tools for managing API keys or handling billing, but these are not essential for the primary use case.
Maintenance
Related MCP Connectors
Open AI models through one OpenAI-compatible API: chat, live model list, prices and cost estimates.
350 chat, image and speech models on one API key, prices readable without a key
Search UnoRouter models, free ones included, check prices and chat through one OpenAI-compatible key
Chat with any LLM, generate images, browse models and check your usage and costs.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides integration with OpenRouter.ai, allowing access to various AI models through a unified interface.4302 npm64Apache 2.0
- AlicenseBqualityBmaintenanceProvides chat and image analysis capabilities through OpenRouter.ai's diverse model ecosystem, enabling both text conversations and powerful multimodal image processing with various AI models.11501 npm103Apache 2.0
- FlicenseBqualityDmaintenanceProvides access to OpenRouter.ai's diverse model ecosystem for text chat and image analysis capabilities, with support for multimodal conversations and automatic image optimization.712 npm-
- AlicenseNot gradedqualityDmaintenanceProvides seamless access to 200+ AI models through OpenRouter's unified API, featuring multi-model collaboration, vision support, intelligent benchmarking, and collective intelligence capabilities for enhanced decision-making.1,013 npm10MIT