mcp-ollama-account-rotation

┌──────────────────────────────────────────┐
│              MCP Client                   │
│    (Claude Code / OpenCode / etc.)       │
└─────────────────┬────────────────────────┘
                  │ MCP Protocol (stdio/SSE)
                  ▼
┌──────────────────────────────────────────┐
│          FastMCP Server                   │
│   Tools: chat, generate, list_models     │
│   Resources: models://, accounts://      │
├──────────────────────────────────────────┤
│          Request Router                   │
│   select account → forward → classify    │
├──────────────────────────────────────────┤
│   Account Manager    │   Retry Engine    │
│   State Manager      │   Health Checker  │
│   HTTP Client        │   Logger/Metrics  │
└──────────────────────────────────────────┘
                  │
                  ▼
         Ollama Cloud API
    https://api.ollama.com

# Prerequisites: Python 3.11+
pip install -e .
# Or with uv:
uv sync

ollama_base_url: "https://api.ollama.com"
retry:
  max_attempts: 3
  backoff_base: 2.0
  backoff_max: 60.0
  jitter: 0.1
rotation:
  strategy: "round_robin"
health:
  interval_seconds: 60
  timeout_seconds: 10
timeouts:
  request_seconds: 60
  connect_seconds: 10
logging:
  level: "INFO"
  format: "json"
  output: "console"

{
  "accounts": [
    {
      "email": "user1@example.com",
      "api_key": "ollama-api-key-1"
    },
    {
      "email": "user2@example.com",
      "api_key": "ollama-api-key-2"
    }
  ]
}

# stdio transport (default)
ollama-router

# custom config
ollama-router -c /path/to/config.yaml

# SSE transport
ollama-router --transport sse --port 8000

{
  "mcpServers": {
    "ollama-router": {
      "command": "ollama-router",
      "args": ["-c", "data/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "ollama-router": {
      "command": "ollama-router",
      "args": ["-c", "data/config.yaml"]
    }
  }
}

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy app

# Linting
ruff check app
ruff format app