OpenRouter MCP Server

🚀 Complete Setup Guide

Follow these steps exactly to get up and running in 5 minutes:

Prerequisites

• Docker installed and running (Get Docker)
• Python 3.8+ installed (Get Python)
• Claude Code desktop app (Get Claude Code)
• OpenRouter API key (Get API Key)

Step 1: Clone Repository

git clone https://github.com/slyfox1186/claude-code-openrouter.git
cd claude-code-openrouter

Step 2: Get Your OpenRouter API Key

1. Go to OpenRouter.ai
2. Sign up or log in to your account
3. Navigate to "Keys" in your dashboard
4. Create a new API key
5. Copy the key (starts with sk-or-v1-)

Step 3: Configure Environment

Create your .env file with your API key:

cat > .env << 'EOF'
# Required: Your OpenRouter API Key
OPENROUTER_API_KEY=sk-or-v1-your_actual_api_key_here

# OpenRouter API Configuration
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# Default Model Settings
DEFAULT_MODEL=moonshotai/kimi-k2-thinking
DEFAULT_TEMPERATURE=0.7
DEFAULT_MAX_TOKENS=1048576
DEFAULT_MAX_REASONING_TOKENS=16384

# Tool Configuration
ENABLE_WEB_SEARCH=true
FORCE_INTERNET_SEARCH=true

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=openrouter_mcp.log

# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60

# MCP Transport
MAX_MESSAGE_SIZE=10485760
MAX_CONCURRENT_REQUESTS=10
EOF

⚠️ IMPORTANT: Replace sk-or-v1-your_actual_api_key_here with your actual OpenRouter API key!

Step 4: Build and Start

# Make scripts executable
chmod +x tools/docker_manager.py add_mcp.sh

# Build and start the container in one command
python3 tools/docker_manager.py build && python3 tools/docker_manager.py start

Step 5: Connect to Claude Code

# Add MCP server to Claude Code
./add_mcp.sh

Step 6: Verify Setup

Test that everything is working:

# Check container status
python3 tools/docker_manager.py status

# View logs (should show "Simple OpenRouter MCP Server starting...")
python3 tools/docker_manager.py logs

🎉 Success! You can now use any OpenRouter model in Claude Code.

✨ Key Features

🧠 Intelligent Model Selection

• Context-Aware: Automatically chooses the best model based on your request
• Smart Qwen Handling: model: "qwen" intelligently selects between qwen3-max (general) or qwen3-coder-plus (coding)
• No More Errors: Eliminates fuzzy matching failures with LLM-powered decisions

🔧 Advanced Capabilities

• 400+ AI Models: Access to all OpenRouter models including GPT-4, Claude, Gemini, DeepSeek, etc.
• 1M+ Token Support: Send massive files without errors (1,048,576 token limit)
• Web Search Integration: Gemini automatically searches for current information
• Conversation Memory: Continue conversations with full context preservation
• Multi-Model Collaboration: Use /call-openrouter command for structured workflows

🛡️ Production Ready

• Graceful Shutdown Protection: Survives Claude Code disconnects without breaking
• Rate Limiting: Built-in protection against API limits
• Error Handling: Comprehensive error recovery and logging
• Docker Containerized: Isolated, reproducible environment

🎯 Quick Test

Try these commands in Claude Code to verify everything works:

# Test basic functionality
openrouter-docker - chat (promp

... [View full README on GitHub](https://github.com/slyfox1186/claude-code-openrouter#readme)