mcp-openrouter AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies (uses uv)
uv sync

# Install with dev dependencies
uv sync --dev

# Install MCP server for Claude Code
claude mcp add openrouter --scope user -- uv run --directory /path/to/mcp-openrouter mcp-openrouter

# Run the server (requires API key)
keyenv run -- uv run mcp-openrouter

# Run tests (requires API key for integration tests)
keyenv run -- uv run pytest tests/

# Run a single test
keyenv run -- uv run pytest tests/test_tools.py::TestChatTool::test_chat_returns_string -v

# Lint with ruff
uv run ruff check src/
uv run ruff format src/

Configuration

Environment variables (private values declared in .keyenv.toml are injected with keyenv run -- ...; non-secret defaults may remain in .env):

Variable	Description
OPENROUTER_API_KEY	Required. Your OpenRouter API key
DEFAULT_TEXT_MODEL	Default model for chat tool (e.g., anthropic/claude-sonnet-4)
DEFAULT_IMAGE_MODEL	Default model for generate_image tool (e.g., google/gemini-3-pro-image-preview)
DEFAULT_CODE_MODEL	Default model for code-related tasks
DEFAULT_VISION_MODEL	Default model for vision tasks
DEFAULT_EMBEDDING_MODEL	Default model for embed tool (e.g., mistralai/mistral-embed-2312)

When default models are configured, the model parameter becomes optional in tool calls.

Architecture

This is an MCP (Model Context Protocol) server built with FastMCP that exposes OpenRouter's API as tools.

Key components:

• src/mcp_openrouter/server.py - MCP server with tool definitions (chat, generate_image, embed, list_models, find_models)
• src/mcp_openrouter/client.py - OpenRouterClient class handling API requests with retry logic
• src/mcp_openrouter/config.py - Configuration management for default models

Flow: MCP tools in server.py → get_client() → OpenRouterClient methods → OpenRouter API