A Model Context Protocol (MCP) server for OpenRouter API with Collective Intelligence - Multi-model consensus, ensemble reasoning, and collaborative problem solving
npm install @physics91/openrouter-mcpnpx
bash
Initialize configuration
npx @physics91/openrouter-mcp init
Start the server
npx @physics91/openrouter-mcp start
`
$3
`bash
Install globally
npm install -g @physics91/openrouter-mcp
Initialize and start
openrouter-mcp init
openrouter-mcp start
`
📋 Prerequisites
- Node.js 16+: Required for CLI interface
- Python 3.9+: Required for the MCP server backend
- OpenRouter API Key: Get one free at openrouter.ai
🛠️ Installation & Configuration
$3
1. Visit OpenRouter
2. Sign up for a free account
3. Navigate to the API Keys section
4. Create a new API key
$3
`bash
npx @physics91/openrouter-mcp init
`
This will:
- Prompt you for your OpenRouter API key
- Create a .env configuration file
- Optionally set up Claude Desktop integration
$3
`bash
npx @physics91/openrouter-mcp start
`
The server will start on localhost:8000 by default.
🎯 Usage
$3
`bash
Show help
npx openrouter-mcp --help
Initialize configuration
npx openrouter-mcp init
Start the server
npx openrouter-mcp start [options]
Check server status
npx openrouter-mcp status
Configure Claude Desktop integration
npx openrouter-mcp install-claude
Configure Claude Code CLI integration
npx openrouter-mcp install-claude-code
`
$3
`bash
Custom port and host
npx openrouter-mcp start --port 9000 --host 0.0.0.0
Enable verbose logging
npx openrouter-mcp start --verbose
Enable debug mode
npx openrouter-mcp start --debug
`
🤖 Claude Desktop Integration
$3
`bash
npx openrouter-mcp install-claude
`
This automatically configures Claude Desktop to use OpenRouter models.
$3
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json
`json
{
"mcpServers": {
"openrouter": {
"command": "npx",
"args": ["openrouter-mcp", "start"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key"
}
}
}
}
`
Then restart Claude Desktop.
💻 Claude Code CLI Integration
$3
`bash
npx openrouter-mcp install-claude-code
`
This automatically configures Claude Code CLI to use OpenRouter models.
$3
Add to your Claude Code CLI config file at ~/.claude/claude_code_config.json:
`json
{
"mcpServers": {
"openrouter": {
"command": "npx",
"args": ["openrouter-mcp", "start"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key"
}
}
}
}
`
$3
Once configured, you can use OpenRouter models directly in your terminal:
`bash
Chat with different AI models
claude "Use GPT-4 to explain this complex algorithm"
claude "Have Claude Opus review my Python code"
claude "Ask Llama 2 to suggest optimizations"
Model discovery and comparison
claude "List all available AI models and their pricing"
claude "Compare GPT-4 and Claude Sonnet for code generation"
Usage tracking
claude "Show my OpenRouter API usage for today"
claude "Which AI models am I using most frequently?"
`
For detailed setup instructions, see Claude Code CLI Integration Guide.
🛠️ Available MCP Tools
Once integrated with Claude Desktop or Claude Code CLI, you'll have access to these tools:
$3
Chat with any available AI model.
Parameters:
- model: Model ID (e.g., "openai/gpt-4o", "anthropic/claude-3.5-sonnet")
- messages: Conversation history
- temperature: Creativity level (0.0-2.0)
- max_tokens: Maximum response length
- stream: Enable streaming responses
Example:
`json
{
"model": "openai/gpt-4o",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain quantum computing"}
],
"temperature": 0.7
}
`
$3
Get comprehensive information about all available models with enhanced metadata.
Parameters:
- filter_by: Optional filter by model name
- provider: Filter by provider (openai, anthropic, google, etc.)
- category: Filter by category (chat, image, reasoning, etc.)
- capabilities: Filter by specific capabilities
- performance_tier: Filter by tier (premium, standard, economy)
- min_quality_score: Minimum quality score (0-10)
Returns:
- Model IDs, names, descriptions with enhanced metadata
- Provider and category classification
- Detailed pricing and context information
- Capability flags (vision, functions, streaming, etc.)
- Performance metrics and quality scores
- Version information and latest model indicators
$3
Track your API usage and costs.
Parameters:
- start_date: Start date (YYYY-MM-DD)
- end_date: End date (YYYY-MM-DD)
Returns:
- Total costs and token usage
- Request counts
- Model-specific breakdowns
$3
Chat with vision-capable models by sending images.
Parameters:
- model: Vision-capable model ID (e.g., "openai/gpt-4o", "anthropic/claude-3-opus", "google/gemini-pro-vision")
- messages: Conversation history (supports both text and image content)
- images: List of images (file paths, URLs, or base64 strings)
- temperature: Creativity level (0.0-2.0)
- max_tokens: Maximum response length
Image Format Support:
- File paths: /path/to/image.jpg, ./image.png
- URLs: https://example.com/image.jpg
- Base64: Direct base64 strings (with or without data URI prefix)
Example - Multiple Images:
`json
{
"model": "openai/gpt-4o",
"messages": [
{"role": "user", "content": "Compare these images and describe the differences"}
],
"images": [
{"data": "/home/user/image1.jpg", "type": "path"},
{"data": "https://example.com/image2.png", "type": "url"},
{"data": "data:image/jpeg;base64,/9j/4AAQ...", "type": "base64"}
]
}
`
Features:
- Automatic image format detection and conversion
- Image resizing for API size limits (20MB max)
- Support for JPEG, PNG, GIF, and WebP formats
- Batch processing of multiple images
$3
Get all vision-capable models.
Parameters: None
Returns:
- List of models that support image analysis
- Model capabilities and pricing information
- Context window sizes for multimodal content
Example Vision Models:
- openai/gpt-4o: OpenAI's latest multimodal model
- openai/gpt-4o-mini: Fast and cost-effective vision model
- anthropic/claude-3-opus: Most capable Claude vision model
- anthropic/claude-3-sonnet: Balanced Claude vision model
- google/gemini-pro-vision: Google's multimodal AI
- meta-llama/llama-3.2-90b-vision-instruct: Meta's vision-capable Llama model
$3
Compare multiple AI models with the same prompt.
Parameters:
- models: List of model IDs to benchmark
- prompt: The prompt to send to each model
- temperature: Temperature setting (0.0-2.0)
- max_tokens: Maximum response tokens
- runs_per_model: Number of runs per model for averaging
Returns:
- Performance metrics (response time, cost, tokens)
- Model rankings by speed, cost, and reliability
- Individual responses from each model
$3
Compare the best models from different categories.
Parameters:
- categories: List of categories to compare
- prompt: Test prompt
- models_per_category: Number of top models per category
Returns:
- Category-wise comparison results
- Best performers in each category
$3
Retrieve historical benchmark results.
Parameters:
- limit: Maximum number of results to return
- days_back: Number of days to look back
- model_filter: Optional model ID filter
Returns:
- List of past benchmark results
- Performance trends over time
- Summary statistics
$3
Export benchmark results in different formats.
Parameters:
- benchmark_file: Benchmark result file to export
- format: Output format ("markdown", "csv", "json")
- output_file: Optional custom output filename
Returns:
- Exported report file path
- Export status and summary
$3
Advanced model comparison with weighted metrics.
Parameters:
- models: List of model IDs to compare
- weights: Metric weights (speed, cost, quality, throughput)
- include_cost_analysis: Include detailed cost analysis
Returns:
- Weighted performance rankings
- Cost-effectiveness analysis
- Usage recommendations for different scenarios
---
🧠 Collective Intelligence Tools
The following advanced tools leverage multiple AI models for enhanced accuracy and insights:
$3
Generate chat completion using collective intelligence with multiple models to reach consensus.
Parameters:
- prompt: The prompt to process collectively
- models: Optional list of specific models to use
- strategy: Consensus strategy ("majority_vote", "weighted_average", "confidence_threshold")
- min_models: Minimum number of models to use (default: 3)
- max_models: Maximum number of models to use (default: 5)
- temperature: Sampling temperature (default: 0.7)
- system_prompt: Optional system prompt for all models
Returns:
- consensus_response: The agreed-upon response
- agreement_level: Level of agreement between models
- confidence_score: Confidence in the consensus
- participating_models: List of models that participated
- individual_responses: Responses from each model
- quality_metrics: Accuracy, consistency, and completeness scores
$3
Perform ensemble reasoning using specialized models for different aspects of complex problems.
Parameters:
- problem: Problem to solve with ensemble reasoning
- task_type: Type of task ("reasoning", "analysis", "creative", "factual", "code_generation")
- decompose: Whether to decompose the problem into subtasks
- models: Optional list of specific models to use
- temperature: Sampling temperature (default: 0.7)
Returns:
- final_result: The combined reasoning result
- subtask_results: Results from individual subtasks
- model_assignments: Which models handled which subtasks
- reasoning_quality: Quality metrics for the reasoning process
- processing_time: Total processing time
- strategy_used: Decomposition strategy used
$3
Intelligently select the best model for a given task using adaptive routing.
Parameters:
- query: Query for adaptive model selection
- task_type: Type of task ("reasoning", "creative", "factual", "code_generation", "analysis")
- performance_requirements: Performance requirements (accuracy, speed thresholds)
- constraints: Task constraints (max cost, timeout, etc.)
Returns:
- selected_model: The chosen model ID
- selection_reasoning: Why this model was selected
- confidence: Confidence in the selection (0-1)
- alternative_models: Other viable options with scores
- routing_metrics: Performance metrics used in selection
- expected_performance: Predicted performance characteristics
$3
Validate content quality and accuracy across multiple models for quality assurance.
Parameters:
- content: Content to validate across models
- validation_criteria: Specific validation criteria (e.g., "factual_accuracy", "technical_correctness")
- models: Optional list of models to use for validation
- threshold: Validation threshold (0-1, default: 0.7)
Returns:
- validation_result: Overall validation result ("VALID" or "INVALID")
- validation_score: Numerical validation score (0-1)
- validation_issues: Issues found by multiple models
- model_validations: Individual validation results from each model
- recommendations: Suggested improvements
- confidence: Confidence in the validation result
$3
Solve complex problems through collaborative multi-model interaction and iterative refinement.
Parameters:
- problem: Problem to solve collaboratively
- requirements: Problem requirements and constraints
- constraints: Additional constraints (budget, time, resources)
- max_iterations: Maximum number of iteration rounds (default: 3)
- models: Optional list of specific models to use
Returns:
- final_solution: The collaborative solution
- solution_path: Step-by-step solution development
- alternative_solutions: Alternative approaches considered
- collaboration_quality: Quality metrics for the collaboration
- component_contributions: Individual model contributions
- convergence_metrics: How the solution evolved over iterations
---
🔒 Security Best Practices
This project implements Defense in Depth security architecture with multiple layers of protection. For complete security documentation, see SECURITY.md.
$3
CRITICAL: API keys must NEVER be stored in configuration files.
Recommended Approach: Environment Variables
Windows:
`cmd
set OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
`
Linux/macOS:
`bash
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
Make permanent:
echo 'export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here' >> ~/.bashrc
source ~/.bashrc
`
The system actively prevents insecure API key storage:
- ❌ API keys in config files are rejected with security errors
- ⚠️ Warnings issued if API key is provided as CLI argument
- ✅ Validation ensures keys are set as environment variables only
$3
Default: Privacy Mode (Recommended)
By default, all user prompts and model responses are redacted from logs and saved results:
`python
✅ SECURE: Content is redacted
benchmark_models(
models=["openai/gpt-4", "anthropic/claude-3.5-sonnet"],
prompt="Your sensitive prompt here"
# Results saved with: ""
)
`
Opt-In: Verbose Logging (Debug Only)
To include actual content (use only for debugging):
`python
⚠️ WARNING: This logs actual prompt/response content
benchmark_models(
models=["openai/gpt-4"],
prompt="Debug prompt",
include_prompts_in_logs=True # Explicit consent required
)
`
A privacy warning will be logged:
`
PRIVACY WARNING: Logging prompt content is enabled.
Prompts may contain sensitive or personal information.
`
$3
The system automatically sanitizes sensitive data:
- API Keys: Masked in all logs (sk-or...MASKED)
- Request Headers: Authorization tokens redacted
- Payloads: Only metadata logged by default (message count, length)
- Responses: Content truncated in error messages (100 char max)
- Errors: No sensitive data in exception messages
$3
| Feature | Status | Protection |
|---------|--------|------------|
| API Key Storage | ✅ Enforced | Environment variables only |
| Config File Validation | ✅ Active | Rejects keys in configs |
| Privacy-Preserving Logs | ✅ Default | Content redacted by default |
| Error Message Redaction | ✅ Active | Response bodies truncated |
| Data Sanitization | ✅ Automatic | All logs sanitized |
| Opt-In Verbose Mode | ⚠️ Available | With explicit warnings |
$3
This project implements controls aligned with:
- OWASP Top 10 (2021): A01, A02, A09
- CWE-798: Hard-coded credentials prevention
- CWE-532: Information exposure through logs prevention
- NIST SP 800-53: AC-3, IA-5, AU-2
$3
- Complete Security Policy - Comprehensive security documentation
- Threat Model - Threats mitigated and residual risks
- Advanced Secrets Management - OS keychain and cloud integration
$3
Before deploying to production:
- [ ] API key set as environment variable (never in config)
- [ ] Privacy mode enabled (default) for all benchmarks
- [ ] Verbose logging disabled (or used only for debugging)
- [ ] Config directory permissions restricted (chmod 700 ~/.claude)
- [ ] API key rotation policy implemented (90 days recommended)
- [ ] Logs reviewed for sensitive data before sharing
---
🔧 Configuration
$3
Create a .env file in your project directory:
`env
OpenRouter API Configuration
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_APP_NAME=openrouter-mcp
OPENROUTER_HTTP_REFERER=https://localhost
Server Configuration
HOST=localhost
PORT=8000
LOG_LEVEL=info
Cache Configuration
CACHE_TTL_HOURS=1
CACHE_MAX_ITEMS=1000
CACHE_FILE=openrouter_model_cache.json
`
$3
| Variable | Description | Default |
|----------|-------------|---------|
| OPENROUTER_API_KEY | Your OpenRouter API key | Required |
| OPENROUTER_APP_NAME | App identifier for tracking | "openrouter-mcp" |
| OPENROUTER_HTTP_REFERER | HTTP referer header | "https://localhost" |
| HOST | Server bind address | "localhost" |
| PORT | Server port | "8000" |
| LOG_LEVEL | Logging level | "info" |
| CACHE_TTL_HOURS | Model cache TTL in hours | "1" |
| CACHE_MAX_ITEMS | Max items in memory cache | "1000" |
| CACHE_FILE | Cache file path | "openrouter_model_cache.json" |
📊 Popular Models
Here are some popular models available through OpenRouter:
$3
- openai/gpt-4o: Most capable multimodal GPT-4 model (text + vision)
- openai/gpt-4o-mini: Fast and cost-effective with vision support
- openai/gpt-4: Most capable text-only GPT-4 model
- openai/gpt-3.5-turbo: Fast and cost-effective text model
$3
- anthropic/claude-3-opus: Most capable Claude model (text + vision)
- anthropic/claude-3-sonnet: Balanced capability and speed (text + vision)
- anthropic/claude-3-haiku: Fast and efficient (text + vision)
$3
- meta-llama/llama-3.2-90b-vision-instruct: Meta's flagship vision model
- meta-llama/llama-3.2-11b-vision-instruct: Smaller vision-capable Llama
- meta-llama/llama-2-70b-chat: Meta's text-only flagship model
- mistralai/mixtral-8x7b-instruct: Efficient mixture of experts
- microsoft/wizardlm-2-8x22b: High-quality instruction following
$3
- google/gemini-pro-vision: Google's multimodal AI (text + vision)
- google/gemini-pro: Google's text-only model
- cohere/command-r-plus: Great for RAG applications
- perplexity/llama-3-sonar-large-32k-online: Web-connected model
Use list_available_models to see all available models and their pricing.
🐛 Troubleshooting
$3
1. Python not found
`bash
Check Python installation
python --version
If not installed, download from python.org
Make sure Python is in your PATH
`
2. Missing Python dependencies
`bash
Install manually if needed
pip install -r requirements.txt
For multimodal/vision features
pip install Pillow>=10.0.0
`
3. API key not configured
`bash
Re-run initialization
npx openrouter-mcp init
`
4. Port already in use
`bash
Use a different port
npx openrouter-mcp start --port 9000
`
5. Claude Desktop not detecting server
- Restart Claude Desktop after configuration
- Check config file path and format
- Verify API key is correct
$3
Enable debug logging for detailed troubleshooting:
`bash
npx openrouter-mcp start --debug
`
$3
Check server configuration and status:
`bash
npx openrouter-mcp status
`
🧪 Development
$3
`bash
Install development dependencies
pip install -r requirements-dev.txt
Run tests
npm run test
Run tests with coverage
npm run test:coverage
Lint code
npm run lint
Format code
npm run format
`
$3
`
openrouter-mcp/
├── bin/ # CLI scripts
│ ├── openrouter-mcp.js # Main CLI entry point
│ └── check-python.js # Python environment checker
├── src/openrouter_mcp/ # Python MCP server
│ ├── client/ # OpenRouter API client
│ │ └── openrouter.py # Main API client with vision support
│ ├── handlers/ # MCP tool handlers
│ │ ├── chat.py # Text-only chat handlers
│ │ ├── multimodal.py # Vision/multimodal handlers
│ │ └── benchmark.py # Model benchmarking handlers
│ └── server.py # Main server entry point
├── tests/ # Test suite
│ ├── test_chat.py # Chat functionality tests
│ ├── test_multimodal.py # Multimodal functionality tests
│ └── test_benchmark.py # Benchmarking functionality tests
├── examples/ # Usage examples
│ └── multimodal_example.py # Multimodal usage examples
├── docs/ # Documentation
├── requirements.txt # Python dependencies (includes Pillow)
└── package.json # Node.js package config
``