@orcarouter/mcp

OrcaRouter MCP Server

Official MCP server for the OrcaRouter LLM gateway.

English | 日本語 | 中文 | 한국어 | Deutsch | Français | Español | Italiano | Русский | Português | Tiếng Việt | हिन्दी

Browse OrcaRouter's model catalog and run chat completions from inside any Model Context Protocol client — Claude Desktop, Claude Code, Cursor, Windsurf, Zed, or anything else that speaks the protocol.

Catalog browsing works without an API key — compare pricing and capabilities before signing up.

What you can do

• 🗺️ Discover providers and models without an API key
• 💬 Run chat completions through any served model
• 🧠 Auto-route requests through your workspace's orcarouter/auto router (cost / quality / balanced / LinUCB / gated-adaptive strategies)
• 🔁 Configure fallback chains (primary + up to 4 fallbacks) for resilience
• 📊 Filter models server-side by provider, capability, or minimum context window
• 🎯 Inspect detailed model cards: pricing, context, latency, supported endpoints
• 🔌 Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP client

Examples

Try saying things like:

• "List all providers on OrcaRouter"
• "Show me all Anthropic models with their pricing"
• "Get details about minimax/minimax-m2.7"
• "Chat with orcarouter/auto and explain quantum computing"

Quick Start

Claude Code (CLI one-liner)

claude mcp add orcarouter -s user \
  -e ORCAROUTER_API_KEY=sk-orca-your-key \
  -- npx -y @orcarouter/mcp

Other clients (config-file path)

• Copy the example config for your MCP client into the client's config file:

  Client	Example	Action
  Claude Desktop	claude-desktop.json	Replace
  Claude Code	claude-code.json	Merge
  Cursor	cursor.json	Replace
  Windsurf	windsurf.json	Replace

  See examples/README.md for the config-file paths and notes on Zed and other clients.

• Replace sk-or-... in the copied file with your OrcaRouter API key.

• Restart your MCP client.

The root .mcp.json is the same config in the Open Plugins standard location, so registry/discovery tools that scan for it (e.g. cursor.directory) can pick this server up automatically.

Requires Node.js 18 or later. The ORCAROUTER_API_KEY env var is only required for orcarouter_chat; catalog tools work without it.

Tools

• orcarouter_chat — run a chat completion (with optional fallback chain)
• orcarouter_models_list — browse the catalog (pricing, context, capabilities)
• orcarouter_model_card — detailed info for one model
• orcarouter_providers_list — list providers with model counts

Full input schemas are exposed at runtime via the MCP tools/list method — your MCP client (Claude Desktop, Cursor, etc.) reads them automatically.

Configuration

Name	Required	Description
ORCAROUTER_API_KEY	optional	OrcaRouter API key. Required only for orcarouter_chat.
ORCAROUTER_BASE_URL	optional	API base URL. Defaults to https://api.orcarouter.ai.
ORCAROUTER_REQUEST_TIMEOUT	optional	Per-request HTTP timeout in seconds. Defaults to 300.

Security

API keys are read from environment variables, never logged, and only sent to the OrcaRouter API. See SECURITY.md for the vulnerability disclosure policy.

Development

# bun (preferred)
bun install
bun run test
bun run typecheck
bun run build

# or with npm
npm install
npm test
npm run typecheck
npm run build

The build produces an ESM bundle at dist/index.js with a #!/usr/bin/env node shebang, runnable as the orcarouter-mcp binary.

Contributing

See CONTRIBUTING.md. For newcomer-friendly tasks, browse the good first issue label.

License

MIT