README.md•10.7 kB
# OpenRouter MCP Server
[](https://github.com/heltonteixeira/openrouterai)
[](CHANGELOG.md)
[](https://www.typescriptlang.org/)
[](LICENSE)
A Model Context Protocol (MCP) server providing seamless integration with OpenRouter.ai's diverse model ecosystem. Access various AI models through a unified, type-safe interface with built-in caching, rate limiting, and error handling.
<a href="https://glama.ai/mcp/servers/xdnmf8yei0"><img width="380" height="200" src="https://glama.ai/mcp/servers/xdnmf8yei0/badge" alt="OpenRouter Server MCP server" /></a>
## Features
- **Model Access**
- Direct access to all OpenRouter.ai models
- Automatic model validation and capability checking
- Default model configuration support
- **Performance Optimization**
- Smart model information caching (1-hour expiry)
- Automatic rate limit management
- Exponential backoff for failed requests
- **Unified Response Format**
- Consistent `ToolResult` structure for all responses
- Clear error identification with `isError` flag
- Structured error messages with context
## Installation
```bash
pnpm install @mcpservers/openrouterai
```
## Configuration
### Prerequisites
1. Get your OpenRouter API key from [OpenRouter Keys](https://openrouter.ai/keys)
2. Choose a default model (optional)
### Environment Variables
* `OPENROUTER_API_KEY`: **Required**. Your OpenRouter API key.
* `OPENROUTER_DEFAULT_MODEL`: Optional. The default model to use if not specified in the request (e.g., `openrouter/auto`).
* `OPENROUTER_MAX_TOKENS`: Optional. Default maximum number of tokens to generate if `max_tokens` is not provided in the request.
* `OPENROUTER_PROVIDER_QUANTIZATIONS`: Optional. Comma-separated list of default quantization levels to filter by (e.g., `fp16,int8`) if `provider.quantizations` is not provided in the request. (Phase 1)
* `OPENROUTER_PROVIDER_IGNORE`: Optional. Comma-separated list of default provider names to ignore (e.g., `mistralai,openai`) if `provider.ignore` is not provided in the request. (Phase 1)
* `OPENROUTER_PROVIDER_SORT`: Optional. Default sort order for providers ("price", "throughput", or "latency"). Overridden by `provider.sort` argument. (Phase 2)
* `OPENROUTER_PROVIDER_ORDER`: Optional. Default prioritized list of provider IDs (JSON array string, e.g., `'["openai/gpt-4o", "anthropic/claude-3-opus"]'`). Overridden by `provider.order` argument. (Phase 2)
* `OPENROUTER_PROVIDER_REQUIRE_PARAMETERS`: Optional. Default boolean (`true` or `false`) to only use providers supporting all specified request parameters. Overridden by `provider.require_parameters` argument. (Phase 2)
* `OPENROUTER_PROVIDER_DATA_COLLECTION`: Optional. Default data collection policy ("allow" or "deny"). Overridden by `provider.data_collection` argument. (Phase 2)
* `OPENROUTER_PROVIDER_ALLOW_FALLBACKS`: Optional. Default boolean (`true` or `false`) to control fallback behavior if preferred providers fail. Overridden by `provider.allow_fallbacks` argument. (Phase 2)
```env
# Example .env file content
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=openrouter/auto
OPENROUTER_MAX_TOKENS=1024
OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8
OPENROUTER_PROVIDER_IGNORE=openai,anthropic
OPENROUTER_PROVIDER_SORT=price
OPENROUTER_PROVIDER_ORDER='["openai/gpt-4o", "anthropic/claude-3-opus"]'
OPENROUTER_PROVIDER_REQUIRE_PARAMETERS=true
OPENROUTER_PROVIDER_DATA_COLLECTION=deny
OPENROUTER_PROVIDER_ALLOW_FALLBACKS=false
```
OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8
OPENROUTER_PROVIDER_IGNORE=openai,anthropic
```
### Setup
Add to your MCP settings configuration file (`cline_mcp_settings.json` or `claude_desktop_config.json`):
```json
{
"mcpServers": {
"openrouterai": {
"command": "npx",
"args": ["@mcpservers/openrouterai"],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"OPENROUTER_DEFAULT_MODEL": "optional-default-model",
"OPENROUTER_MAX_TOKENS": "1024",
"OPENROUTER_PROVIDER_QUANTIZATIONS": "fp16,int8",
"OPENROUTER_PROVIDER_IGNORE": "openai,anthropic"
}
}
}
}
## Response Format
All tools return responses in a standardized structure:
```typescript
interface ToolResult {
isError: boolean;
content: Array<{
type: "text";
text: string; // JSON string or error message
}>;
}
```
**Success Example:**
```json
{
"isError": false,
"content": [{
"type": "text",
"text": "{\"id\": \"gen-123\", ...}"
}]
}
```
**Error Example:**
```json
{
"isError": true,
"content": [{
"type": "text",
"text": "Error: Model validation failed - 'invalid-model' not found"
}]
}
```
## Available Tools
### `chat_completion`
Sends a request to the OpenRouter Chat Completions API.
**Input Schema:**
* `model` (string, optional): The model to use (e.g., `openai/gpt-4o`, `google/gemini-pro`). Overrides `OPENROUTER_DEFAULT_MODEL`. Defaults to `openrouter/auto` if neither is set.
* **Model Suffixes:** You can append `:nitro` to a model ID (e.g., `openai/gpt-4o:nitro`) to potentially route to faster, experimental versions if available. Append `:floor` (e.g., `mistralai/mistral-7b-instruct:floor`) to use the cheapest available variant of a model, often useful for testing or low-cost tasks. Note: Availability of `:nitro` and `:floor` variants depends on OpenRouter.
* `messages` (array, required): An array of message objects conforming to the OpenAI chat completion format.
* `temperature` (number, optional): Sampling temperature. Defaults to 1.
* `max_tokens` (number, optional): Maximum number of tokens to generate in the completion. Overrides `OPENROUTER_MAX_TOKENS`.
* `provider` (object, optional): Provider routing configuration. Overrides corresponding `OPENROUTER_PROVIDER_*` environment variables.
* `quantizations` (array of strings, optional): List of quantization levels to filter by (e.g., `["fp16", "int8"]`). Only models matching one of these levels will be considered. Overrides `OPENROUTER_PROVIDER_QUANTIZATIONS`. (Phase 1)
* `ignore` (array of strings, optional): List of provider names to exclude (e.g., `["openai", "anthropic"]`). Models from these providers will not be used. Overrides `OPENROUTER_PROVIDER_IGNORE`. (Phase 1)
* `sort` ("price" | "throughput" | "latency", optional): Sort providers by the specified criteria. Overrides `OPENROUTER_PROVIDER_SORT`. (Phase 2)
* `order` (array of strings, optional): A prioritized list of provider IDs (e.g., `["openai/gpt-4o", "anthropic/claude-3-opus"]`). Overrides `OPENROUTER_PROVIDER_ORDER`. (Phase 2)
* `require_parameters` (boolean, optional): If true, only use providers that support all specified request parameters (like tools, functions, temperature). Overrides `OPENROUTER_PROVIDER_REQUIRE_PARAMETERS`. (Phase 2)
* `data_collection` ("allow" | "deny", optional): Specify whether providers are allowed to collect data from the request. Overrides `OPENROUTER_PROVIDER_DATA_COLLECTION`. (Phase 2)
* `allow_fallbacks` (boolean, optional): If true (default), allows falling back to other providers if the preferred ones fail or are unavailable. If false, fails the request if preferred providers cannot be used. Overrides `OPENROUTER_PROVIDER_ALLOW_FALLBACKS`. (Phase 2)
**Example Usage:**
```json
{
"tool": "chat_completion",
"arguments": {
"model": "anthropic/claude-3-haiku",
"messages": [
{ "role": "user", "content": "Explain the concept of quantization in AI models." }
],
"max_tokens": 500,
"provider": {
"quantizations": ["fp16"],
"ignore": ["openai"],
"sort": "price",
"order": ["anthropic/claude-3-haiku", "google/gemini-pro"],
"require_parameters": true,
"allow_fallbacks": false
}
}
}
```
This example requests a completion from `anthropic/claude-3-haiku`, limits the response to 500 tokens. It specifies provider routing options: prefer `fp16` quantized models, ignore `openai` providers, sort remaining providers by `price`, prioritize `anthropic/claude-3-haiku` then `google/gemini-pro`, require the chosen provider to support all request parameters (like `max_tokens`), and disable fallbacks (fail if the prioritized providers cannot fulfill the request).
### search_models
Search and filter available models:
```typescript
interface ModelSearchRequest {
query?: string;
provider?: string;
minContextLength?: number;
capabilities?: {
functions?: boolean;
vision?: boolean;
};
}
// Response: ToolResult with model list or error
```
### get_model_info
Get detailed information about a specific model:
```typescript
{
model: string; // Model identifier
}
```
### validate_model
Check if a model ID is valid:
```typescript
interface ModelValidationRequest {
model: string;
}
// Response:
// Success: { isError: false, valid: true }
// Error: { isError: true, error: "Model not found" }
```
## Error Handling
The server provides structured errors with contextual information:
```typescript
// Error response structure
{
isError: true,
content: [{
type: "text",
text: "Error: [Category] - Detailed message"
}]
}
```
**Common Error Categories:**
- `Validation Error`: Invalid input parameters
- `API Error`: OpenRouter API communication issues
- `Rate Limit`: Request throttling detection
- `Internal Error`: Server-side processing failures
**Handling Responses:**
```typescript
async function handleResponse(result: ToolResult) {
if (result.isError) {
const errorMessage = result.content[0].text;
if (errorMessage.startsWith('Error: Rate Limit')) {
// Handle rate limiting
}
// Other error handling
} else {
const data = JSON.parse(result.content[0].text);
// Process successful response
}
}
```
## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed information about:
- Development setup
- Project structure
- Feature implementation
- Error handling guidelines
- Tool usage examples
```bash
# Install dependencies
pnpm install
# Build project
pnpm run build
# Run tests
pnpm test
```
## Changelog
See [CHANGELOG.md](./CHANGELOG.md) for recent updates including:
- Unified response format implementation
- Enhanced error handling system
- Type-safe interface improvements
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.