# Mcp Openrouter

> MCP server for OpenRouter.ai model catalog with advanced filtering, search, and comparison capabilities

- **Type:** MCP server
- **Install:** `agentstack add mcp-hulupeep-mcp-openrouter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Hulupeep](https://agentstack.voostack.com/s/hulupeep)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Hulupeep](https://github.com/Hulupeep)
- **Source:** https://github.com/Hulupeep/mcp-openrouter

## Install

```sh
agentstack add mcp-hulupeep-mcp-openrouter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenRouter MCP Server

[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](https://opensource.org/licenses/MIT)
[](./tests)

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

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

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

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

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

```bash
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`:

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

#### Linux
Edit `~/.config/Claude/claude_desktop_config.json`:

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

#### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```typescript
{
  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

```bash
# 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](LICENSE) file for details.

## Acknowledgments

- Built on the

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Hulupeep](https://github.com/Hulupeep)
- **Source:** [Hulupeep/mcp-openrouter](https://github.com/Hulupeep/mcp-openrouter)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hulupeep-mcp-openrouter
- Seller: https://agentstack.voostack.com/s/hulupeep
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.