# OpenCollective MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI agents programmatic access to [OpenCollective](https://opencollective.com/), [Hetzner Cloud](https://www.hetzner.com/), and [Cloudflare](https://www.cloudflare.com/) — enabling automated bookkeeping, collective management, and invoice handling without manual intervention.
## What is it?
This MCP server exposes 22 tools that let AI agents interact with:
- **OpenCollective GraphQL API v2** — Manage collectives, submit expenses, process payments, query transactions, and handle members
- **Hetzner Cloud invoices** — Automatically fetch, parse, and reconcile hosting invoices
- **Cloudflare billing** — Track CDN and hosting costs via the billing history API
### The Problem
If you run an OpenCollective-backed project with infrastructure on Hetzner, you face a tedious monthly ritual:
1. Log into Hetzner → navigate to invoices → download the PDF
2. Manually extract the amount, date, and line items
3. Log into OpenCollective → create a new expense → copy-paste the data
4. Submit and wait for approval
Repeat every month. Forever.
**This MCP automates it.**
## Who is it for?
- **Open collective maintainers** who want to automate expense workflows
- **DevOps engineers** running infrastructure on Hetzner who track costs via OpenCollective
- **AI developers** building agents that need to manage budgets, expenses, or financial reporting
- **Bookkeepers** tired of copy-pasting invoice data between systems
## What can it do?
### OpenCollective Operations (13 tools)
| Tool | What it does |
|------|--------------|
| `oc_get_account` | Get detailed info about any collective (balance, stats, social links) |
| `oc_search_accounts` | Search across all OpenCollective accounts |
| `oc_get_logged_in_account` | Get the authenticated user's account |
| `oc_edit_account` | Update collective profile (name, description, tags, currency) |
| `oc_get_members` | List members, backers, and their donation totals |
| `oc_list_expenses` | Query expenses with rich filters (status, type, date, tags) |
| `oc_get_expense` | Get full expense details by ID |
| `oc_create_expense` | Submit new expenses (INVOICE, RECEIPT, GRANT, etc.) |
| `oc_edit_expense` | Modify existing expenses |
| `oc_delete_expense` | Remove expenses |
| `oc_process_expense` | Approve, reject, pay, hold, or release expenses |
| `oc_list_transactions` | Query the ledger (credits/debits, linked expenses) |
| `oc_execute_graphql` | Escape hatch for any GraphQL operation |
### Hetzner Operations (6 tools)
| Tool | What it does |
|------|--------------|
| `hetzner_list_invoices` | List all invoices (paginated) |
| `hetzner_get_invoice` | Get a specific invoice by ID |
| `hetzner_get_latest_invoice` | Fetch the most recent invoice |
| `hetzner_get_invoice_pdf` | Download invoice as PDF (base64) |
| `hetzner_parse_invoice_pdf` | Extract structured data from invoice PDF |
| `hetzner_get_invoice_details` | Get line-item breakdown from usage portal |
### Cloudflare Operations (3 tools)
| Tool | What it does |
|------|--------------|
| `cloudflare_list_invoices` | List billing history (paginated). Auto-converts USD to EUR using historical ECB rates |
| `cloudflare_get_invoice` | Get a specific billing item by ID. Includes EUR conversion |
| `cloudflare_get_latest_invoice` | Fetch the most recent billing item. Returns `amount_cents_eur` ready for OpenCollective |
## The Monthly Bookkeeping Workflow
```python
# 1. Fetch the latest Hetzner invoice
invoice = hetzner_get_latest_invoice()
# 2. Submit it as an expense to your collective
oc_create_expense(
account_slug="my-collective",
description=f"Hetzner Cloud - {invoice['date']}",
expense_type="INVOICE",
payee_slug="my-org",
items=[{
"description": f"Cloud services - {invoice['date']}",
"amount_cents": invoice['amount_cents'],
"currency": "EUR"
}],
tags=["hetzner", "hosting"]
)
```
```python
# For Cloudflare (automatically converts USD to EUR)
invoice = cloudflare_get_latest_invoice()
oc_create_expense(
account_slug="my-collective",
description=f"Cloudflare - {invoice['date']}",
expense_type="INVOICE",
payee_slug="my-org",
items=[{
"description": f"Cloudflare services - {invoice['date']}",
"amount_cents": invoice['amount_cents_eur'], # Already converted!
"currency": "EUR"
}],
tags=["cloudflare", "hosting", "cdn"]
)
```
That's it. One agent prompt = one booked expense.
## What it's NOT
- **Not a replacement for human judgment** — Expenses still need approval based on your collective's policies
- **Not a financial advisory tool** — It moves data, not money; you control the payouts
- **Not limited to Hetzner** — The `oc_execute_graphql` tool lets you run any OpenCollective operation, so you can manage Stripe payouts, Wise transfers, or budget forecasting
- **Not a GUI** — It's a backend for AI agents; use the OpenCollective dashboard for manual tasks
## Quick Start
### 1. Clone and install
```bash
git clone https://github.com/your-org/opencollective-mcp.git
cd opencollective-mcp
pip install -e .
```
### 2. Configure environment
Copy `.env.example` to `.env` and fill in:
```bash
cp .env.example .env
# Edit .env with your credentials
```
| Variable | Required for | How to get it |
|----------|-------------|---------------|
| `OPENCOLLECTIVE_TOKEN` | Write operations | [OpenCollective dashboard](https://opencollective.com/dashboard) → For Developers → Personal Tokens |
| `HETZNER_ACCOUNT_EMAIL` | Hetzner invoice tools | Your Hetzner account email |
| `HETZNER_ACCOUNT_PASSWORD` | Hetzner invoice tools | Your Hetzner password |
| `HETZNER_TOTP_SECRET` | Hetzner invoice tools (if 2FA) | Shown when you enable 2FA |
| `CLOUDFLARE_API_TOKEN` | Cloudflare billing tools | [Cloudflare dashboard](https://dash.cloudflare.com) → My Profile → API Tokens → Create Token with "Billing:Read" permission |
### 3. Run the server
```bash
# Direct
python -m opencollective_mcp
# Or via installed script
opencollective-mcp
```
### 4. Connect to Claude Desktop
Add to your `~/.claude.json`:
```json
{
"mcpServers": {
"opencollective": {
"command": "python",
"args": ["-m", "opencollective_mcp"],
"env": {
"OPENCOLLECTIVE_TOKEN": "your-token",
"HETZNER_ACCOUNT_EMAIL": "you@example.com",
"HETZNER_ACCOUNT_PASSWORD": "your-password",
"CLOUDFLARE_API_TOKEN": "your-cloudflare-token"
}
}
}
}
```
## Why build this?
Because **infrastructure costs should be visible, automated, and auditable** — exactly what OpenCollective provides for open source projects.
We built this to solve our own bookkeeping pain: tracking Hetzner hosting costs for [Going Dark](https://opencollective.com/goingdark) and automatically submitting them as expenses each month. Now our AI agent does it.
If you run a collective with cloud infrastructure, this saves you 15–30 minutes every month — and eliminates human error from manual data entry.
## License
Apache License 2.0
---
Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk), [httpx](https://www.python-httpx.org/), and [Playwright](https://playwright.dev/).
