Files
mcp-home/AGENTS.md
T

15 KiB

mcp-home

Self-hosted MCP (Model Context Protocol) servers for the OpenClaw assistants (mycroft/jarvis). Provides access to personal data services via HTTP endpoints with OAuth (client_credentials).

Architecture

8 independent MCP servers, each on its own port, bound to 0.0.0.0:

  • Mail (Port 5100) — searches IMAP backup Maildirs, reads attachments, creates drafts
  • Calendar (Port 5101) — CalDAV against Baikal (Produktiv; Radicale-Fallback nur fuer Test-User mcptest) (events + tasks/reminders, travel time, geocoding, alarms)
  • Contacts (Port 5102) — CardDAV against Baikal (Produktiv; Radicale-Fallback nur fuer Test-User mcptest) (contacts + photos)
  • Files (Port 5103) — WebDAV against oCIS (full CRUD, images inline, documents as blobs)
  • Notes (Port 5104) — Joplin Data API (notes + attachments)
  • OpenWearables (Port 5105) — read-only Wearable-Daten (Sleep, Activity, Workouts, Timeseries) aus Open Wearables (/opt/openwearables), nur eigene Daten (s. u.)
  • Ghostfolio (Port 5120) — Portfolio-Tracker via Ghostfolio-REST-API (Port 3333); read+write (Konten, Activities, Performance, Dividenden)
  • ActualBudget (Port 5121) — Haushaltsbudget; read+write via Node-Sidecar /opt/actualbudget-mcp/sidecar (systemd actualbudget-sidecar, 127.0.0.1:5106) auf ActualBudget-Server (Port 5006)

Zugriff intern (Standard): Die OpenClaw-Container (mycroft/jarvis) erreichen die Server ueber das Docker-Gateway 172.26.0.1:<port>/mcp (openclaw-net). Die URLs stehen in den Container-Configs /mnt/ssd/openclaw/<agent>/data/openclaw.json (mcp.servers.*.url).

Zugriff oeffentlich (seit 2026-09-18): notes, calendar, mail, contacts, files, openwearables, ghostfolio und owamail sind zusaetzlich unter https://<name>.mcp.slohmaier.de/mcp erreichbar (nginx -> 127.0.0.1:, Let's-Encrypt-SAN, Rate-Limit auf /authorize+/token). OpenClaw nutzt fuer diese die oeffentlichen URLs (bewusste Abweichung von der Regel "lokale Routen", damit die Config bei einem Umzug unveraendert bleibt). Weitere Server bei Bedarf nach demselben Muster (vhost + Cert-SAN). Details: README.md, Abschnitt "Oeffentliche Endpunkte".

Auth fuer oeffentliche Clients: OAuth (claude.ai) ODER nicht-ablaufende Service-Tokens (service_tokens.json, Verwaltung ./mint-service-token.sh); common.py prueft Service-Tokens vor den OAuth-Access-Tokens. Zukunfts-Option OAuth/DCR (ChatGPT) siehe README.md.

Firewall: iptables raw-PREROUTING blockt die Ports 5100-5105,5120,5121 fuer alle Quellen ausserhalb 172.26.0.0/16 (openclaw-net). nginx erreicht die Ports via 127.0.0.1 (ACCEPT-Regel). Regel in /etc/iptables/rules.v4 (netfilter-persistent).

OpenWearables (Port 5105)

Server: /opt/mcp-servers/openwearables/server.py, Config /opt/mcp-servers/openwearables/config.json (chmod 600, enthaelt den gemeinsamen OpenWearables-API-Key und das User-ID-Mapping).

Tools: get_users, get_sleep_summary, get_activity_summary, get_workout_events, get_timeseries. Alle read-only, gegen die interne Open-Wearables-API (http://127.0.0.1:8000), NIE ueber Cloudflare.

User-Trennung (wichtig): Der OpenWearables-API-Key ist GLOBAL (nicht pro User gescoped). Die Trennung passiert im Server: config.json mappt den OAuth-User (stefan/kati) auf die jeweilige OpenWearables-User-UUID (user_id_map). Die OpenWearables-User-ID wird IMMER aus dem Login des Clients bestimmt, nie aus Tool-Argumenten. mycroft sieht also nur Stefans Daten, jarvis nur Katis.

  • MCP-Server in openclaw.json: openwearables -> http://172.26.0.1:5105/mcp
  • systemd: mcp-openwearables.service

All servers share common.py for OAuth + user resolution.

Auth Flow

claude.ai uses OAuth 2.0 Authorization Code + PKCE. client_credentials is also supported (used by tests).

  1. claude.ai discovers /.well-known/oauth-authorization-server
  2. GET /authorize → auto-approves valid client_id, redirects with code
  3. POST /token (authorization_code + code_verifier, optional client_secret) → access_token
  4. Authorization: Bearer <token> on MCP requests

Access tokens are stored in a shared file .active_tokens.json so all 5 services validate tokens issued by any service. client_secret is verified at token exchange when provided.

User Separation

tokens.json (not in git, chmod 600) maps client_id (stefan, kati, test) → secret. USER_ALIASES in common.py maps test → stefan. Each user sees only their own data; shared CalDAV calendars are visible to both.

Config

  • tokens.json — OAuth client_id/secret per user (gitignored)
  • config.json — all backend credentials (Baikal + Radicale, oCIS, Joplin, IMAP), gitignored. See config.json.example.
  • .active_tokens.json — runtime OAuth tokens (gitignored)

Backends

  • Mail: reads Maildirs under /mnt/ssd/Backup/{stefan,kati}/imap/. Drafts via IMAP APPEND (1blu / Gmail).
  • Calendar/Contacts: Baikal CalDAV/CardDAV on https://baikal.slohmaier.de (Produktiv, seit 2026-09-11). Basen: dav.php/calendars/<user>/ und dav.php/addressbooks/<user>/; Baikal liefert hrefs pfad-absolut (/dav.php/...) und calendar-data/address-data mit Namespace-Prefix cal:/card: — der Parser ist Namespace-agnostisch ((?:[a-zA-Z][a-zA-Z0-9_]*):calendar-data|address-data). sabre inbox/outbox werden herausgefiltert. Backend-Auswahl pro User ueber _serve(user): User in baikal_users (stefan/kati = mycroft/jarvis) → Baikal; andere (Test-User mcptest) → Radicale-Fallback http://127.0.0.1:5232 (Radicale laeuft weiter fuer Tests, mirror-first bis Geraete-Umstellung abgeschlossen). Radicale-URL/Creds/Pfade bleiben in config.json (radicale_url, radicale_users, radicale_calendar_paths, radicale_addressbook_paths).
  • Files: oCIS WebDAV on 127.0.0.1:9200/remote.php/dav/files/<user>/. oCIS username may differ from MCP user (mapping in config).
  • Notes: Joplin Data API via joplin-cli sync clients on 127.0.0.1:41184 (stefan) / 41185 (kati). See /opt/joplin-mcp/README.md. NOT the Joplin Server sync API (that has no clean REST/search).
  • Ghostfolio: Ghostfolio-REST-API on 127.0.0.1:3333 (JWT-Token /opt/ghostfolio/migration/.auth-token). Read+write.
  • ActualBudget: Node-Sidecar (/opt/actualbudget-mcp/sidecar, systemd actualbudget-sidecar) on 127.0.0.1:5106 (RPC), der @actual-app/api kapselt und den ActualBudget-Server (Port 5006) anspricht.

Files

  • common.py — OAuth (authorize/token/metadata), Bearer middleware, user resolution (contextvars), config loader
  • mail/server.py — Maildir reader; tools: list_accounts, list_folders, search_mail, read_mail (lists attachments), read_attachment, create_draft
  • calendar/server.py — CalDAV REPORT + vobject; events/tasks CRUD, travel time, geocoding, reminders. Timed events/tasks werden mit TZID=Europe/Berlin (pytz) geschrieben (naive Eingaben lokalisiert, Offsets/Z konvertiert; Bugfix 2026-09-30, vorher floating -> Baikal las +2h). create/update_event+create/update_task haben ein timezone-Argument (IANA, Default Europe/Berlin; z.B. Asia/Hong_Kong fuer Auslands-Termine, lokale Ortszeit eintragen); Ausgabe behaelt die benannte Zone, UTC-Importe werden nach Berlin normalisiert. Delete/Update loesen den echten Ressourcenpfad per UID auf (_find_href), da der Dateiname nicht die UID sein muss (Importe wie medatixx).
  • contacts/server.py — CardDAV; search/get/create, contact photos
  • files/server.py — WebDAV; list/read/write/delete/move/search, images + documents
  • notes/server.py — Joplin Data API; list/search/read/create notes, list_note_resources, read_resource, add/update/delete_attachment
  • ghostfolio/server.py — Ghostfolio-REST-API; portfolio_details, get_performance, get_dividends, list_accounts, create_account, import_activities, list_activities, delete_activity. Schreib-Tools stoessen automatisch update-report.sh an -> accessible-dashboard-Report wird sofort neu gebaut (Details im ghostfolio/README)
  • actualbudget/server.py — Node-Sidecar-RPC; budgets/accounts/transactions/categories/budget/payees CRUD + aql_query
  • tests/ — Schichten: test_smoke.py (NIGHTLY via mcp-tests.timer, nur up+Auth+1 Read/Connector), test_edge.py+test_stress.py+test_all.py (ON-DEMAND via run_full_tests.sh). Doku tests/MCPTEST.md

Dependencies

pip install mcp[cli] httpx vobject python-dateutil pytest

Python 3.12+, venv at ./venv/. joplin-cli (npm global) for Notes backend.

Deployment

Each server is a systemd unit mcp-<name>.service (uvicorn), bound to 0.0.0.0. Zugriff intern via openclaw-net (172.26.0.1:/mcp); einzelne Server zusaetzlich oeffentlich via nginx/TLS (notes/calendar, s. o.). Joplin: joplin-cli-{stefan,kati}.service + joplin-sync.timer (15 min).

Git-Zugang (2026-10-01): Das Gitea-Token lag im Klartext in .git/config (origin-URL). Entfernt; Remote-URL jetzt https://gitea.slohmaier.com/slohmaier/mcp-home.git. Zugang ueber Credential-Store credential.helper = store --file=/root/.git-credentials (mode 600, repo-lokal gesetzt), da Git hier per sudo als root laeuft. Kein Token mehr in .git/config oder im Working Tree.

Content Types (returning binary)

  • Text → TextContent
  • Images (jpg/png/gif/webp) → ImageContent (base64 inline)
  • PDFs → server-seitig zu Text extrahiert bzw. gescannte Seiten als PNG+OCR gerendert (pdfutil.py). claude.ai nimmt KEINE PDF/Dokument-Blobs aus Tool-Results nativ entgegen (nur Text + Bild). Andere Binaerdateien → EmbeddedResource/BlobResourceContents (Blob; wird von claude.ai nicht als Dokument verarbeitet)

Robustheit / Limits

Alle Such-/List-Tools sind gegen grosse Datenmengen abgesichert (single-threaded Server darf nicht haengen): Mail per-Mail try/except + DEADLINE_S/MAX_SCAN; Files search_files SEARCH_DEADLINE_S/SEARCH_MAX_DIRS; Calendar/Contacts PARSE_DEADLINE_S + MAX_RESULTS-Output-Cap. Details + Messwerte: tests/MCPTEST.md.

Adding a New Service

  1. <name>/server.py with FastMCP instance + create_app() (copy mail/server.py pattern)
  2. Import get_current_user, OAUTH_ROUTES, BearerAuthMiddleware, load_config from common.py
  3. systemd unit mcp-<name>.service (bind 0.0.0.0) + iptables-Regel fuer den Port (nur openclaw-net 172.26.0.0/16) + URL in den Container-Configs eintragen
  4. systemd unit mcp-<name>.service
  5. Backend creds in config.json
  6. Tests: Smoke-Read in test_smoke.py + Edge in test_edge.py + Stress in test_stress.py (Funktional in test_all.py); Dashboard + dieses File aktualisieren

Tool Design Guidelines

  • Docstring is the first thing Claude sees — make it actionable ("Call this first", "Use the UID from search results")
  • Annotated[str, Field(description="...")] with example values for every parameter
  • Mark optional params ("Leave empty for all")
  • Reference other tools ("Use read_attachment with the index from read_mail")
  • Return structured text, not JSON
  • Include IDs/keys in output so Claude can chain to detail tools

Test-/Dev-User mcptest

Die Test-Suite laeuft auf einem isolierten mcptest-User (NICHT Stefans Daten): USER_ALIASES = {"test": "mcptest"}. Eigene Backends: Radicale-User mcptest (Calendar/Contacts laufen ueber den Radicale-Fallback in _serve(user), da es keinen Baikal-mcptest gibt), oCIS-User mcptest, lokales Joplin-Profil (:41186, joplin-cli-mcptest.service), Test-Maildir tests/testdata/maildir/. Dient auch als Dev-Sandbox. Vollstaendige Doku + Provisioning: tests/MCPTEST.md. Creds: /root/.mcptest-creds (600) + config.json.

User nova (stefan@slohmaier.com, fuer OpenClaw-Agent Nova)

Nova (Agent im mycroft-Gateway) braucht Business-Mails statt Stefans privater .de-Mails. Dafuer:

  • tokens.json: User nova mit eigenem Client-Secret (token).
  • config.json mail_roots.nova -> /mnt/ssd/Backup/stefan/nova-imap (Symlink auf das .com-Maildir d370128_0-stefanlohmaier). Nova sieht damit NUR das .com-Postfach.
  • Im mycroft-Gateway gibt es einen zusaetzlichen MCP-Server mail-com (Bearer des nova- Users) auf demselben Port 5100. Nova nutzt mail-com, Mycroft nutzt mail (.de).
  • Zugriffstoken fuer nova per mcp-token-refresh-Mechanik oder manuell: POST /token client_credentials mit client_id=nova + secret aus tokens.json.

Calendar: Namens-Aufloesung (exakt vor Teilstring)

Seit 2026-08-20 loest _match_cols Kalender-/Listen-Namen bei allen Schreib-/Loesch-Operationen (create_event, create_task, delete_event, delete_task) so auf: exakter Namens-Treffer zuerst, sonst Teilstring. Grund: Die Shared-Kalender "Kati Stefan" (beschreibbar) und "Kati Stefan JaSi" (read-only, Google-Sync) kollidierten bei Teilstring-Match — ein PUT auf "Kati Stefan" traf sonst den read-only JaSi-Kalender (HTTP 403), obwohl der User (kati/stefan) Schreibrechte auf den richtigen Kalender hat.

Calendar: Loeschen

Der Calendar-MCP hat seit 2026-08-13 delete_event und delete_task (Loeschen per UID). UID kommt aus get_events / get_tasks. Loeschung direkt via CalDAV an das aktive Backend (Baikal fuer stefan/kati, Radicale-Fallback fuer mcptest).

Mail-Drafts mit Anhang

create_draft unterstuetzt seit 2026-08-13 Anhaenge ueber Base64:

  • attachment_filenames (Liste), attachment_contents (Liste, Base64-kodierte Bytes), optional attachment_mimetypes (Liste; sonst application/octet-stream).
  • Der Agent erzeugt einen mehrteiligen (multipart) Draft im IMAP-Drafts-Ordner.
  • Test ok: "Entwurf erstellt mit 1 Anhang/Anhaengen".

Notes: Anhaenge (Attachments)

Der Notes-MCP kann seit 2026-09-16 Anhaenge an Notizen anlegen, aendern und loeschen (vorher nur lesen: list_note_resources / read_resource):

  • add_attachment(note_id, filename, content_base64, mime?, title?) — laedt die Datei via POST /resources hoch (multipart/form-data: Datei im Feld data, Properties als JSON im Feld props) und haengt [title](:/resourceId) ans Ende des Notiz-Bodys an (bei Bildern ![...], damit es inline rendert). Max 25 MB; Inhalt Base64 (data-URL-Prefix und Zeilenumbrueche erlaubt).
  • update_attachment(resource_id, content_base64?, filename?, mime?, title?) — ersetzt den Datei-Inhalt (PUT /resources/:id, multipart) und/oder aendert Titel/MIME (JSON-PUT, wenn kein Inhalt uebergeben wird).
  • delete_attachment(resource_id, note_id?, remove_links?) — loescht das Resource endgueltig (Joplin hat fuer Resources keinen Papierkorb) und entfernt die Markdown-/HTML-Referenzen aus dem Notiz-Body. note_id angeben, damit der Link sicher bereinigt wird: Joplins Endpoint /resources/:id/notes ist unzuverlaessig (Link-Tabelle kann leer bleiben, dann bliebe der Link verwaist).
  • MIME wird aus der Dateiendung geraten, wenn nicht uebergeben.
  • Getestet in tests/test_all.py::TestNotes::test_attachment_crud (mcptest).