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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

1. Verify the config file path is correct
2. Ensure the absolute path to index.js is correct
3. Restart Claude Desktop
4. 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 LICENSE 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