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