OpenRouter Bridge

PyPI version

A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with OpenRouter API. Works with Claude Code, Cursor, VS Code, and other MCP-compatible clients.

✨ Features

• Direct OpenRouter API Integration: Async HTTP calls using httpx
• Simple MCP Tools: Three core functions for queries, file analysis, and batch processing
• Stateless Operation: No sessions, caching, or complex state management
• Production Ready: Robust error handling with configurable timeouts (default: 90 seconds)
• Minimal Dependencies: httpx, python-dotenv, and mcp>=1.0.0
• Async/Await: Full async support for concurrent operations
• Model Flexibility: Support any OpenRouter-compatible model

🚀 Quick Start

Prerequisites

1. Get OpenRouter API Key:

   # Visit https://openrouter.ai/keys
   # Sign up and get your API key
   

2. Set Environment Variable:

   export OPENROUTER_API_KEY="your-api-key-here"
   

Installation

From PyPI:

pip install openrouter-mcp-bridge

Using uvx (recommended for MCP servers):

uvx openrouter-mcp-bridge

Local Development:

# Clone the repository
git clone https://github.com/htooayelwinict/open-bridge.git
cd open-bridge

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Run directly
python -m src

⚙️ Configuration

Environment Variables

Claude Code Configuration

# Add to Claude Code with uvx (recommended)
claude mcp add openrouter-mcp-bridge -s user \
  --env OPENROUTER_API_KEY=sk-or-... \
  --env OPENROUTER_MODEL=anthropic/claude-3.5-sonnet \
  -- uvx openrouter-mcp-bridge

Or add to ~/.claude.json:

{
  "mcpServers": {
    "openrouter-mcp-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["openrouter-mcp-bridge"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-...",
        "OPENROUTER_MODEL": "anthropic/claude-3.5-sonnet"
      }
    }
  }
}

🛠️ Available Tools

📋 Usage Examples

# Basic query
consult_openrouter(
    query="What authentication patterns are used in this project?",
    directory="/path/to/project",
    format="json"
)

# File analysis
consult_openrouter_with_stdin(
    stdin_content=open("src/auth.py").read(),
    prompt="Review this file for security issues",
    directory="/path/to/project"
)

# Batch processing
consult_openrouter_batch(
    queries=[
        {"query": "Analyze authentication patterns"},
        {"query": "Review database implementations"}
    ],
    directory="/path/to/project"
)

🏗️ Architecture

• API-First: Direct async HTTP calls to OpenRouter API
• Stateless: Each tool call is independent with no session state
• Async/Await: Full async support for concurrent operations
• Error Handling: Comprehensive HTTP and timeout error handling

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

Originally forked from shelakh/codex-bridge.

Focus: A simple, reliable bridge between Claude Code and OpenRouter API.