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
Robust Error Handling
- Detailed error messages with context
- Rate limit detection and recovery
- Network timeout handling with retries

Installation

npm install @mcpservers/openrouterai

Configuration

Prerequisites

Get your OpenRouter API key from OpenRouter Keys
Choose a default model (optional)

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

Available Tools

chat_completion

Send messages to OpenRouter.ai models:

{
  model?: string;          // Optional if default model is set
  messages: {
    role: "system" | "user" | "assistant";
    content: string;
  }[];
  temperature?: number;    // Optional (0-2), defaults to 1.0
}

search_models

Search and filter available models:

{
  query?: string;          // Search in name/description
  provider?: string;       // Filter by provider
  minContextLength?: number;
  maxContextLength?: number;
  maxPromptPrice?: number;
  maxCompletionPrice?: number;
  capabilities?: {
    functions?: boolean;   // Function calling support
    tools?: boolean;       // Tool use support
    vision?: boolean;      // Image processing support
    json_mode?: boolean;   // JSON mode support
  };
  limit?: number;          // Default: 10, max: 50
}

get_model_info

Get detailed information about a specific model:

{
  model: string;           // Model identifier
}

validate_model

Check if a model ID is valid:

{
  model: string;           // Model identifier to validate
}

Rate Limiting

The server implements intelligent rate limit handling:

Tracks remaining requests through response headers
Automatically waits when rate limits are reached
Implements exponential backoff for failed requests
Provides clear error messages for rate limit issues

Error Handling

The server uses McpError for MCP-specific errors with clear messages:

Invalid model errors
API rate limiting
Authentication issues
Network errors
Invalid parameter errors

Development

See CONTRIBUTING.md for detailed information about:

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

Changelog

See CHANGELOG.md for version history and migration guides.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.