mcp-openrouter by Hulupeep - MCP Server

OpenRouter MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to the OpenRouter.ai model catalog. Query, filter, compare, and discover AI models with advanced search capabilities and real-time pricing data.

Features

🔍 Advanced Search & Filtering

Filter by provider, price, context length, and modality
Search models by name or description
Sort by multiple criteria (price, context, name, date)

💰 Cost Optimization

Find cheapest models meeting your requirements
Compare pricing across providers
Per-million-token pricing breakdowns

📊 Model Comparison

Side-by-side model comparisons
Detailed specifications and capabilities
Architecture and parameter information

🚀 Real-Time Data

Live data from OpenRouter API
Auto-refreshing cache (5-minute TTL)
Fallback to cached data if API unavailable

📝 Ready-to-Use Code Examples

curl, Python, and JavaScript examples for each model
OpenRouter API integration snippets
Best practices and configuration

Installation

Prerequisites

Node.js >= 18.0.0
Claude Desktop or any MCP-compatible client

Quick Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/mcp-openrouter.git
cd mcp-openrouter

# Install dependencies
npm install

# Run tests to verify installation
npm test

Add to Claude Code

The easiest way to add this server is using the claude mcp add command:

# Navigate to the project directory
cd /path/to/mcp-openrouter

# Add the MCP server (use absolute path)
claude mcp add openrouter -- node $(pwd)/src/index.js

That's it! The server is now available in Claude Code.

Scope Options

You can configure where the server is available:

# Add for current project only (default)
claude mcp add openrouter -- node $(pwd)/src/index.js

# Add for all your projects (user scope)
claude mcp add --scope user openrouter -- node $(pwd)/src/index.js

# Add to share with your team (project scope - creates .mcp.json)
claude mcp add --scope project openrouter -- node $(pwd)/src/index.js

Verify Installation

Check that your server is installed:

# List all MCP servers
claude mcp list

# Get details for this server
claude mcp get openrouter

Remove Server

If needed, you can remove the server:

claude mcp remove openrouter

Add to Claude Desktop (Alternative)

If you prefer to use Claude Desktop, you can manually edit the config file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-openrouter/src/index.js"]
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-openrouter/src/index.js"]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\mcp-openrouter\\src\\index.js"]
    }
  }
}

Restart Claude Desktop after updating the configuration.

Available Tools

1. `list_models`

List all available models with optional filtering and sorting.

Parameters:

provider (string): Filter by provider (e.g., "anthropic", "openai", "google")
category (string): Filter by category
max_price_per_1m_tokens (number): Maximum price per 1M input tokens (USD)
min_context_length (number): Minimum context window size
modality (string): Filter by input modality ("text", "image", "audio", "video")
sort_by (string): Sort by "price", "context_length", "name", or "created"
sort_order (string): "asc" or "desc" (default: "asc")

Example Response:

{
  "count": 12,
  "models": [
    {
      "id": "anthropic/claude-3-haiku",
      "name": "Anthropic: Claude 3 Haiku",
      "provider": "anthropic",
      "description": "Fast and affordable Claude model",
      "context_length": 200000,
      "pricing_per_1m_tokens": {
        "input": "0.25",
        "output": "1.25"
      },
      "modalities": {
        "input": ["text", "image"],
        "output": ["text"]
      },
      "created": "2024-03-01T00:00:00.000Z"
    }
  ]
}

2. `get_model`

Get comprehensive details about a specific model.

Parameters:

model_id (string, required): The model ID (e.g., "anthropic/claude-3-opus")

Returns:

Complete model specifications
Pricing breakdown (per-token and per-1M-tokens)
Architecture details and supported modalities
Supported parameters and defaults
Usage examples in curl, Python, and JavaScript

3. `list_providers`

List all model providers with statistics.

Returns:

{
  "count": 53,
  "providers": [
    {
      "name": "openai",
      "model_count": 43,
      "models": ["openai/gpt-4-turbo", "openai/gpt-4", ...]
    }
  ]
}

4. `compare_models`

Compare multiple models side by side.

Parameters:

model_ids (array, required): Array of model IDs to compare

Example:

{
  "model_ids": [
    "anthropic/claude-3-opus",
    "openai/gpt-4-turbo",
    "google/gemini-pro-1.5"
  ]
}

5. `search_models`

Search models by name or description.

Parameters:

query (string, required): Search query
search_in (string): "name", "description", or "both" (default: "both")

6. `get_cheapest_models`

Find the most cost-effective models meeting your criteria.

Parameters:

min_context_length (number): Minimum context window required
modality (string): Required input modality
limit (number): Maximum number of results (default: 10)

7. `refresh_cache`

Force refresh the model data cache.

Resources

`openrouter://models/all`

Complete JSON list of all available models with full metadata.

`openrouter://providers/all`

JSON list of all providers with model counts and model IDs.

Use Cases

1. Cost Optimization for Production

Scenario: You need to reduce API costs while maintaining quality.

"Find the 5 cheapest models with at least 100,000 context length that support vision"

Use: get_cheapest_models
{
  "min_context_length": 100000,
  "modality": "image",
  "limit": 5
}

Result: Discover cost-effective alternatives like Claude 3 Haiku or Gemini Flash that can save 60-80% on API costs.

2. Model Selection for New Project

Scenario: Starting a new project and need to evaluate options.

Workflow:

1. "List all Anthropic models sorted by context length"
   → Understand available options

2. "Compare claude-3-opus, claude-3-sonnet, and claude-3-haiku"
   → See pricing, capabilities, and trade-offs

3. "Get detailed information for anthropic/claude-3-sonnet"
   → Review specifications and get integration code

Outcome: Make informed decisions based on your specific requirements (budget, context needs, capabilities).

3. Multi-Modal Application Development

Scenario: Building an app that needs vision and text understanding.

"Search for models that support vision"

Use: search_models
{
  "query": "vision",
  "search_in": "both"
}

Then filter: "Show only models with 128K+ context and under $5 per 1M tokens"

Use: list_models
{
  "modality": "image",
  "min_context_length": 128000,
  "max_price_per_1m_tokens": 5.0,
  "sort_by": "price"
}

Outcome: Identify models like GPT-4 Vision, Claude 3, or Gemini that fit your budget and requirements.

4. Provider Evaluation

Scenario: Evaluating which provider offers the best selection for your needs.

"List all providers and their model counts"

Use: list_providers

Then drill down: "Show all Google models with their pricing"

Use: list_models
{
  "provider": "google",
  "sort_by": "price"
}

Outcome: Compare provider offerings, pricing strategies, and model variety.

5. Migration Planning

Scenario: Migrating from one model to another due to deprecation or cost.

1. "Get details for my current model: openai/gpt-4"

2. "Find alternatives with similar context length and capabilities"
   Use: list_models with similar specifications

3. "Compare my shortlist of alternatives"
   Use: compare_models with selected model IDs

Outcome: Smooth migration with full understanding of API changes needed.

6. Budget-Constrained Development

Scenario: Building a prototype with limited budget.

"Find free or cheapest models with at least 32K context"

Use: get_cheapest_models
{
  "min_context_length": 32000,
  "limit": 10
}

Outcome: Discover free-tier models or ultra-affordable options for development and testing.

7. Specialized Task Selection

Scenario: Need a model optimized for coding tasks.

"Search for models optimized for coding"

Use: search_models
{
  "query": "code",
  "search_in": "description"
}

Refine: "Show only models under $2 per 1M tokens"

Use: list_models with price filter

Outcome: Find specialized models like Code Llama, DeepSeek Coder, or coding-optimized variants.

8. Batch Processing Cost Analysis

Scenario: Planning to process large volumes of data.

1. "Compare pricing for high-volume processing across providers"
   → Get pricing data for multiple models

2. Calculate: "If processing 1 billion tokens per month..."
   → Model A: $15/month
   → Model B: $50/month
   → Model C: $150/month

Outcome: Choose the right model for your scale and budget.

Example Scenarios

Scenario 1: Building a Customer Support Chatbot

Requirements:

Context: 50K tokens (to include conversation history + knowledge base)
Budget: Under $3 per 1M tokens
Response quality: High
Speed: Important but not critical

Query:

"Find models with 50K+ context, under $3 per 1M input tokens, sorted by price"

list_models({
  min_context_length: 50000,
  max_price_per_1m_tokens: 3.0,
  sort_by: "price",
  sort_order: "asc"
})

Decision: After comparing options, select Claude 3 Haiku ($0.25/1M) for excellent quality at low cost.

Scenario 2: Document Analysis with Vision

Requirements:

Must support both text and image inputs
Large context for entire documents (100K+)
Accuracy is critical

Query:

"Find vision-capable models with 100K+ context"

list_models({
  modality: "image",
  min_context_length: 100000,
  sort_by: "context_length",
  sort_order: "desc"
})

Compare top options:

compare_models({
  model_ids: [
    "anthropic/claude-3-opus",
    "google/gemini-pro-1.5",
    "openai/gpt-4-turbo"
  ]
})

Decision: Gemini Pro 1.5 with 1M context for complex document analysis.

Scenario 3: Startup MVP with Limited Budget

Requirements:

Minimal cost during development
Need to test various use cases
Will scale later

Strategy:

1. "Find free models"
   get_cheapest_models({ limit: 10 })

2. Test with free tier models:
   - Development: Free models
   - Staging: Low-cost models ($0.10-$1.00/1M)
   - Production: Premium models when funded

Outcome: Build and test MVP without burning through capital.

Scenario 4: Research Project Comparing Model Capabilities

Requirements:

Need to test same prompts across multiple models
Document model specifications
Compare outputs scientifically

Workflow:

1. "List all models from major providers"
   list_models() → Get comprehensive catalog

2. "Get detailed specs for comparison set"
   get_model() for each model in study

3. Document:
   - Architecture differences
   - Context window impacts
   - Pricing vs performance correlation

Outcome: Comprehensive research data for publication.

Data Structure

Each model includes:

{
  id: string;                    // Unique identifier (e.g., "anthropic/claude-3-opus")
  name: string;                  // Human-readable name
  provider: string;              // Provider name
  description: string;           // Model description
  created: string;               // ISO 8601 creation date
  context_length: number;        // Maximum context window
  pricing: {
    prompt_per_token: string;           // Per-token input cost
    completion_per_token: string;       // Per-token output cost
    image_per_token: string;            // Per-image cost (if applicable)
    request: string;                    // Per-request cost (if applicable)
    per_1m_tokens: {
      input: string;             // Formatted cost per 1M input tokens
      output: string;            // Formatted cost per 1M output tokens
    }
  };
  architecture: {
    input_modalities: string[];  // Supported inputs (text, image, audio, video)
    output_modalities: string[]; // Supported outputs
    tokenizer: string;           // Tokenizer type
    instruct_type: string;       // Instruction format
  };
  top_provider: {
    is_moderated: boolean;       // Content moderation enabled
    context_length: number;      // Provider-specific context limit
    max_completion_tokens: number; // Maximum output tokens
  };
  supported_parameters: string[];  // Supported API parameters
  default_parameters: object;      // Default parameter values
  usage_example: {
    curl: string;                // curl example
    python: string;              // Python example
    javascript: string;          // JavaScript example
  }
}

Caching Strategy

Cache Duration: 5 minutes
Auto-Refresh: Yes
Fallback: Uses cached data if API unavailable
Manual Refresh: Available via refresh_cache tool

This ensures:

Fresh data for accurate pricing and availability
Reduced API calls for better performance
Resilience during API downtime

Development

# Run in development mode with auto-reload
npm run dev

# Run unit tests
npm test

# Run integration tests
node tests/integration.test.js

Testing

The project includes comprehensive test coverage:

Unit Tests (`npm test`)

Provider extraction logic
Pricing calculations
Filtering and sorting
Search functionality
Cache behavior

Integration Tests (`node tests/integration.test.js`)

Full MCP protocol communication
Live API data fetching
All tool endpoints
Resource access

All tests pass with 100% success rate.

API Reference

The server uses the OpenRouter API:

Endpoint: https://openrouter.ai/api/v1/models
Documentation: https://openrouter.ai/docs/api-reference/list-available-models
Rate Limits: Respects OpenRouter rate limiting
Authentication: Not required for model listing

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Roadmap

Add model performance benchmarks
Include model availability status
Add historical pricing data
Support for custom filtering expressions
Model recommendation engine
Cost estimation calculator
WebSocket support for real-time updates
Model deprecation tracking

Troubleshooting

Server not appearing in Claude Desktop

Verify the config file path is correct
Ensure the absolute path to index.js is correct
Restart Claude Desktop
Check Claude Desktop logs for errors

Cache not refreshing

Use the refresh_cache tool to force an immediate refresh:

refresh_cache()

Models not appearing in search results

Check your filter criteria aren't too restrictive
Verify the search query spelling
Try searching in "both" name and description

License

MIT License - see file for details.

Acknowledgments

Built on the Model Context Protocol
Data provided by OpenRouter.ai
Inspired by the need for intelligent model discovery

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
MCP Documentation: https://modelcontextprotocol.io

Made with ❤️ for the AI developer community

Hulupeep/mcp-openrouter

OpenRouter MCP Server

Features

Installation

Prerequisites

Quick Setup

Add to Claude Code

Scope Options

Verify Installation

Remove Server

Add to Claude Desktop (Alternative)

macOS

Linux

Windows

Available Tools

1. list_models

2. get_model

3. list_providers

4. compare_models

5. search_models

6. get_cheapest_models

7. refresh_cache

Resources

openrouter://models/all

openrouter://providers/all

Use Cases

1. Cost Optimization for Production

2. Model Selection for New Project

3. Multi-Modal Application Development

4. Provider Evaluation

5. Migration Planning

6. Budget-Constrained Development

7. Specialized Task Selection

8. Batch Processing Cost Analysis

Example Scenarios

Scenario 1: Building a Customer Support Chatbot

Scenario 2: Document Analysis with Vision

Scenario 3: Startup MVP with Limited Budget

Scenario 4: Research Project Comparing Model Capabilities

Data Structure

Caching Strategy

Development

Testing

Unit Tests (npm test)

Integration Tests (node tests/integration.test.js)

API Reference

Contributing

Roadmap

Troubleshooting

Server not appearing in Claude Desktop

Cache not refreshing

Models not appearing in search results

License

Acknowledgments

Support

1. `list_models`

2. `get_model`

3. `list_providers`

4. `compare_models`

5. `search_models`

6. `get_cheapest_models`

7. `refresh_cache`

`openrouter://models/all`

`openrouter://providers/all`

Unit Tests (`npm test`)

Integration Tests (`node tests/integration.test.js`)