appflowy_mcp — Homeserver Coolify

A self-owned MCP server for Moritz's self-hosted AppFlowy Cloud (https://appflowy.mchristoffers.dev). Oeffentlich erreichbar ueber den geteilten Homelab-Cloudflare-Tunnel, fuer den claude.ai Web-Connector (der kann nicht ins Tailnet). Der MCP-Server hat kein eigenes Login — deshalb sitzt oauth-agents davor, siehe unten.

Dieses Repo implementiert den MCP-Server selbst (Python/FastMCP), inspiriert von, aber unabhaengig von den bestehenden m2n2/appflowy-mcp / weironz/appflowy_mcp-Projekten. Alle Tools sprechen die native REST-API der bestehenden AppFlowy-Instanz an.

Claude Code Plugin

Dieses Repo ist gleichzeitig ein Claude-Code-Plugin (.claude-plugin/plugin.json

• .mcp.json) und ein Agent-Plugins-1.0.0-Paket (root plugin.json + mcp.json), listet den appflowy-mcp MCP-Server via https://appflowymcp-oauth.mchristoffers.dev/mcp (OAuth) und wird ueber die mchristoffers/claude-marketplace Marketplace installiert. Nichts einzutragen: oauth-agents beantwortet POST /register (Dynamic Client Registration) immer mit demselben statischen Client, und Loopback-Callbacks auf beliebigem Port sind pauschal erlaubt (RFC 8252).

Zugriff

https://appflowymcp-oauth.mchristoffers.dev/mcp

OAuth 2.1 + PKCE, ein Login (GATEWAY_USERNAME/GATEWAY_PASSWORD). Der oauth-Container ist Authorization Server und Gate in einem: er stellt die Tokens aus, prueft den Bearer am /mcp-Pfad und reicht zum unveraenderten MCP-Server durch. Er liefert auch die MCP-Protected-Resource-Metadata unter /.well-known/oauth-protected-resource. Hinter dem Tunnel plain HTTP — TLS terminiert Cloudflare.

Stack

docker-compose.production.yml:

• appflowymcp — eigener Build (Dockerfile), veroeffentlicht keinen Host-Port. Spricht die AppFlowy-REST-API ueber APPFLOWY_BASE_URL an und haelt die GoTrue-Session selbst (login + refresh).
• oauth — ghcr.io/mchristoffers/oauth-agents, Port 8085 (nur der Tunnel-Container erreicht ihn). Volume oauth_data:/data haelt den Signing-Key, sonst logged jeder Redeploy alle Clients aus.

Die AppFlowy-Zugangsdaten (APPFLOWY_EMAIL/APPFLOWY_PASSWORD) + Gateway (GATEWAY_USERNAME/GATEWAY_PASSWORD) liegen nur als Coolify-Environment- Variablen vor, nie in Git.

Immer aktuell

image: ghcr.io/mchristoffers/appflowy_mcp:main plus pull_policy: always. Ein Redeploy zieht damit immer den neuesten Stand. GitHub Actions baut und pusht das Image nach GHCR, dann loest sie den Coolify-Deploy aus und wartet auf das Ergebnis. Die Action laeuft zusaetzlich sonntags 04:05 UTC per schedule und aktualisiert von allein.

Kein Rollback vorgesehen; APPFLOWY_MCP_TAG existiert trotzdem als Coolify-Env-Var — im Notfall auf einen sha-<commit>-Tag setzen, redeployen. Kein Backup noetig: der MCP-Server haelt keinen eigenen Datenbestand (nur das oauth_data-Volume mit dem Signing-Key), er ist jederzeit neu erzeugbar.

Deploy

Push auf main → GitHub Action validiert das Compose, baut+pusht das Image, signiert das Payload und POSTet es an Coolifys manuellen GitHub-Webhook, dann wartet sie auf das Ergebnis. Kein Health-Check auf der URL (Endpoint verlangt jetzt OAuth).

Lokale Entwicklung

uv venv && uv pip install -e ".[collab]"
export APPFLOWY_BASE_URL=... APPFLOWY_EMAIL=... APPFLOWY_PASSWORD=...
fastmcp run src/appflowy_mcp/server.py --transport http --port 8001