opencollective-hetzner-mcp: Instructions file for Codex

OpenCollective MCP Server

A Model Context Protocol server that gives AI agents programmatic access to the OpenCollective GraphQL API v2, Hetzner Cloud invoices, and Cloudflare billing. Built with Python, FastMCP, and httpx.

The primary use case is automated monthly bookkeeping: fetching hosting invoices from Hetzner and Cloudflare, then submitting them as expenses to an OpenCollective collective -- but the server exposes the full range of OpenCollective operations so any agent can manage collectives, expenses, members, and transactions without manual intervention.

Architecture

src/opencollective_mcp/
  __init__.py              Package marker
  __main__.py              `python -m opencollective_mcp` entrypoint
  server.py                FastMCP server -- all 22 tools, input models, lifespan
  client.py                Async GraphQL client for OpenCollective API v2
  queries.py               GraphQL query/mutation strings (organized by domain)
  hetzner.py               Hetzner client wrapper (uses browser automation)
  hetzner_browser.py       Browser automation for Hetzner Accounts login and invoice retrieval
  cloudflare.py            Cloudflare billing client (uses REST API)

Design decisions

Separation of concerns. The GraphQL client (client.py) knows nothing about MCP. The query strings (queries.py) are plain constants. The Hetzner client (hetzner.py) is its own module. The server (server.py) wires them together through FastMCP tools. Any piece can be swapped, tested, or reused independently.

No hardcoded slugs or IDs. Every tool accepts the account slug / ID as a parameter. The server itself stores no state about which collective it operates on.

Authenticated and unauthenticated. Read-only OpenCollective queries (account info, public expenses, transactions, members) work without a token. Write operations and Hetzner calls require their respective tokens via environment variables.