⚡ OpenRouter MCP

Every AI model. One terminal. Zero context switching.

GPT-4   Claude   Gemini   Llama   Mistral   Flux   +300 more

Getting Started · Features · Tools · Development

The Problem

You're in your AI coding assistant. You need a quick GPT-4 opinion. Or a Flux-generated image. Or a side-by-side comparison across three models. That means: leave your editor, open a browser, find the right API, copy-paste keys, lose your flow...

The Fix

Add it to your MCP config and go:

{
  "openrouter": {
    "command": "npx",
    "args": ["-y", "openrouter-mcp-server"],
    "env": {
      "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
    }
  }
}

Now every model on OpenRouter is one tool call away. Chat, image gen, model search, cost tracking — all inline.

---

⚡ Getting Started

Step 1 — Get an API key from openrouter.ai/keys

Step 2 — Add to your MCP config (~/.claude/settings.json or your app's MCP settings):

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "openrouter-mcp-server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
      }
    }
  }
}

Done. The server starts automatically when your MCP client connects.

Alternative: Clone & build from source

git clone https://github.com/overtimepog/OpenrouterMCP.git
cd OpenrouterMCP
bash scripts/setup.sh

---

🎯 Features

Multi-Model Chat Talk to any of 300+ models with multi-turn context, streaming, and tool calling

Image Generation Flux, Stable Diffusion, Gemini — control ratio, resolution, save locally

Model Comparison Same prompt to N models, side-by-side quality, speed, and cost

Cost Tracking Real-time spend per session, per model, per operation

---

📡 MCP Tools

openrouter_chat — Chat with any model

Parameter	Type	Required	Description
model	string	Yes	Model ID (e.g. openai/gpt-4)
messages	array	Yes	[{ role, content }] message array
session_id	string		Continue an existing conversation
stream	boolean		Stream response (default: true)
temperature	number		Randomness 0–2
max_tokens	number		Max tokens to generate
tools	array		OpenAI-compatible function definitions
tool_choice	string		auto / none / required
top_p	number		Nucleus sampling threshold
top_k	number		Top-K sampling
frequency_penalty	number		Frequency penalty (−2 to 2)
presence_penalty	number		Presence penalty (−2 to 2)
reasoning	object		Reasoning tokens ({ effort })
provider	object		Provider routing preferences
models	array		Fallback model list for auto-routing
plugins	array		OpenRouter plugins (e.g. web search)

openrouter_search_models — Advanced model search & compare

Parameter	Type	Description
provider	string	Filter by provider (openai, anthropic, …)
keyword	string	Search in model names
min_context_length	number	Minimum context window
max_context_length	number	Maximum context window
modality	string	text, image, audio
min_price / max_price	number	Price range per token
supports_tools	boolean	Function calling support
supports_streaming	boolean	Streaming support
supports_temperature	boolean	Temperature parameter support
sort_by	string	price, context_length, provider
sort_order	string	asc or desc

openrouter_list_models — List all models with filtering

Parameter	Type	Description
provider	string	Filter by provider
keyword	string	Search in model names
min_context_length	number	Minimum context window
max_context_length	number	Maximum context window
modality	string	Filter by modality
min_price / max_price	number	Price range

openrouter_generate_image — Generate images

Parameter	Type	Required	Description
model	string	Yes	Image model ID
prompt	string	Yes	Image description
aspect_ratio	string		1:1, 16:9, 9:16, etc.
image_size	string		1K, 2K, or 4K
save_path	string		Local save path (.png, .jpg, .webp)

openrouter_get_credits — Check balance & usage

No parameters. Returns credit limit, remaining balance, total usage, and daily/weekly/monthly breakdowns.

openrouter_get_cost_summary — Cost breakdown

Parameter	Type	Description
session_id	string	Costs for a specific session
recent_only	boolean	Only show recent entries

openrouter_get_generation — Generation stats

Parameter	Type	Required	Description
generation_id	string	Yes	The generation ID to look up

Returns tokens, cost, latency, model, and provider info.

openrouter_get_model_endpoints — Provider endpoints & routing

Parameter	Type	Required	Description
model_slug	string	Yes	Model slug (e.g. openai/gpt-4)

Returns all available providers with latency, uptime, pricing, and capabilities.

---

📁 Project Structure

OpenrouterMCP/
└── src/                    TypeScript MCP server
    ├── index.ts            Entry point
    ├── server/             Server bootstrap
    ├── api/                OpenRouter client, cache, rate limits
    ├── session/            Multi-turn conversation management
    ├── cost/               Cost tracking engine
    ├── schemas/            Shared Zod schemas
    ├── tools/              8 tool implementations
    │   ├── chat/
    │   ├── searchModels/
    │   ├── listModels/
    │   ├── imageGeneration/
    │   ├── credits/
    │   ├── costSummary/
    │   ├── generation/
    │   └── modelEndpoints/
    └── utils/              Logger, model validation

---

🛠 Development

npm install          # dependencies
npm run build        # compile
npm test             # 383 tests
npm run dev          # watch mode

---

🔍 Troubleshooting

OPENROUTER_API_KEY not found

echo 'export OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.zshrc && source ~/.zshrc

Invalid API key

Verify at openrouter.ai/keys that the key is correct and active.

Model not found

Model IDs use the format provider/model-name (e.g. openai/gpt-4). Use the openrouter_search_models tool to find current models — never hardcode IDs.

Rate limit exceeded

The server warns before you hit limits. Upgrade your OpenRouter plan or space out requests.

Tools not showing up

1. Check key is set: echo $OPENROUTER_API_KEY
2. Verify your MCP config has the correct server entry
3. Restart your MCP client
4. Try npx -y openrouter-mcp-server directly to check for errors

---

_{MIT License}