OrcaRouter MCP Server

Official MCP server for the OrcaRouter LLM gateway.

Browse [OrcaRouter](https://www.orcarouter.ai)'s model catalog and run chat completions from inside any [Model Context Protocol](https://modelcontextprotocol.io) 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) ```bash claude mcp add orcarouter -s user \ -e ORCAROUTER_API_KEY=sk-orca-your-key \ -- npx -y @orcarouter/mcp ``` ### Other clients (config-file path) 1. Copy the example config for your MCP client into the client's config file: | Client | Example | Action | | --------------- | --------------------------------------------------- | ------- | | Claude Desktop | [claude-desktop.json](examples/claude-desktop.json) | Replace | | Claude Code | [claude-code.json](examples/claude-code.json) | Merge | | Cursor | [cursor.json](examples/cursor.json) | Replace | | Windsurf | [windsurf.json](examples/windsurf.json) | Replace | See [`examples/README.md`](examples/README.md) for the config-file paths and notes on Zed and other clients. 2. Replace `sk-or-...` in the copied file with your [OrcaRouter API key](https://www.orcarouter.ai/console). 3. Restart your MCP client. The root [`.mcp.json`](.mcp.json) is the same config in the [Open Plugins](https://open-plugins.com) standard location, so registry/discovery tools that scan for it (e.g. [cursor.directory](https://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](SECURITY.md) for the vulnerability disclosure policy. ## Development ```sh # 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](CONTRIBUTING.md). For newcomer-friendly tasks, browse the [`good first issue`](https://github.com/Continuum-AI-Corp/orcarouter-mcp-server/labels/good%20first%20issue) label. ## License [MIT](LICENSE)