OpenRouter MCP Server

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.

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

pnpm install @mcpservers/openrouterai

Configuration

Prerequisites

1. Get your OpenRouter API key from OpenRouter 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)

# 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`):

{

"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:

interface ToolResult {
  isError: boolean;
  content: Array;
}

Success Example:

{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "{\"id\": \"gen-123\", ...}"
  }]
}

Error Example:

{
  "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.
• `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.

Example Usage:

{
  "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:

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:

{
  model: string;           // Model identifier
}

validate_model

Check if a model ID is valid:

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:

// 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:

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 for detailed information about:

• Development setup
• Project structure
• Feature implementation
• Error handling guidelines
• Tool usage examples

# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test

Changelog

See 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 file for details.