OpenRouter MCP Server

A Model Context Protocol (MCP) server for OpenRouter. Register it in MCP-compatible clients that can launch a local stdio server to use OpenRouter models for chat, vision, benchmarking, and collective-intelligence workflows.

Features

• MCP tools: chat, model listing, usage stats, vision chat, vision model listing, free chat, free model listing, free model metrics
• Benchmarking suite and performance comparison tools
• Collective intelligence tools (consensus, ensemble reasoning, adaptive routing, cross-model validation, collaborative solving)
• Secure API key storage (OS keychain, encrypted file, or .env) with audit logging
• Streaming responses, caching, and rich model metadata

Quick start

npx @physics91/openrouter-mcp init
npx @physics91/openrouter-mcp start

Global install:

npm install -g @physics91/openrouter-mcp
openrouter-mcp init
openrouter-mcp start

MCP client setup

Client config formats differ, but the launch information is usually the same:

• command: npx
• args: ["@physics91/openrouter-mcp", "start"]
• env: Use only when the client cannot rely on openrouter-mcp init or inherited environment variables.

Recommended credential flow:

• Run npx @physics91/openrouter-mcp init
• Let openrouter-mcp start resolve the API key from secure storage or runtime environment

Client-specific examples:

• Claude Desktop: mcpServers in claude_desktop_config.json
• Claude Code: claude mcp add ... or project .mcp.json
• VS Code: servers in .vscode/mcp.json

See docs/MCP_CLIENT_GUIDE.md for the common flow and client-specific examples.

Prerequisites

• Node.js 16+
• Python 3.10+ (python or python3 must be available in PATH)
• First run attempts dependency install via <python> -m pip install -r requirements.txt
• OpenRouter API key: https://openrouter.ai

DevOps Readiness (Clone -> Test/Build/Deploy)

If you clone this repository and want to trust local DevOps gates immediately, run this baseline once:

git clone <repo-url>
cd openrouter-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
npm install --no-audit --no-fund

Then run the quality/release gates:

1. Build gate (build skill):

ruff check src/ tests/
black --check src/ tests/
isort --check-only src/ tests/

2. Test gate (test skill):

python3 run_tests.py assurance -v

3. Deploy pre-flight (deploy skill):

npm whoami

Notes:

• assurance includes Python test gates and then npm run test:security only after pytest passes.
• If your OS blocks global pip installs (PEP 668), use .venv as shown above.
• npm run build is intentionally a no-op in this project; static quality gates above are the real build criteria.
• Publishing is always manual and intentional: npm publish --access public only after all gates pass and explicit confirmation.

CLI

Use openrouter-mcp <command> or npx @physics91/openrouter-mcp <command>.

Commands:

• start Start the MCP server (stdio)
• init Initialize API key storage
• status Show configuration status
• install-claude Configure Claude Desktop
• install-claude-code Configure Claude Code CLI
• rotate-key Rotate API key across storage
• delete-credentials Remove stored credentials
• security-audit Audit credential storage and permissions
• migrate-encryption Migrate encrypted credentials to v2.0

Global options: --verbose, --debug start options: --host, --port

MCP client integration

• Common MCP client setup: docs/MCP_CLIENT_GUIDE.md
• Claude Desktop shortcut: openrouter-mcp install-claude
• Claude Code CLI shortcut: openrouter-mcp install-claude-code
• Generated server entries use: npx @physics91/openrouter-mcp start

See:

• docs/MCP_CLIENT_GUIDE.md
• docs/CLAUDE_DESKTOP_GUIDE.md
• docs/CLAUDE_CODE_GUIDE.md

Notes

• Vision tools accept images as base64 or URL only (file paths are not supported).
• API keys should not be committed. Use init for secure storage. See SECURITY.md.

Documentation

• docs/INSTALLATION.md
• docs/MCP_CLIENT_GUIDE.md
• docs/CLAUDE_DESKTOP_GUIDE.md
• docs/CLAUDE_CODE_GUIDE.md
• docs/API.md
• docs/SECURITY.md
• docs/MULTIMODAL_GUIDE.md
• docs/BENCHMARK_GUIDE.md
• docs/SECURE_STORAGE_INTEGRATION.md
• docs/QUICK_REFERENCE.md
• docs/USAGE_GUIDE_KR.md
• docs/CLAUDE_CODE_SETUP_KR.md

Contributing

See CONTRIBUTING.md.

Quick setup for local hook enforcement:

pip install -r requirements-dev.txt
pre-commit install

The installed hooks enforce:

• pre-commit fast checks before commit
• commit-msg Conventional Commit format in English
• pre-push smoke tests

Deeper static analysis remains available as advisory/manual checks rather than push blockers. Use pre-commit run --hook-stage manual mypy-advisory --all-files (and the other *-advisory hooks) when you want the broader reports locally.

License

MIT