Self-hosted MCP servers for Claude. Gives Claude access to your email, calendar, contacts, files, and notes — all running on your own hardware, behind OAuth.

Services & Tools

  • Mail — list_accounts, list_folders, search_mail (full text), read_mail (lists attachments), read_attachment (image/PDF/text), download_attachment (Anhang als Datei ins Agent-Workspace), create_draft
    • download_attachment (2026-09-04): schreibt den Anhang (account/folder/key aus search_mail, Index aus read_mail) als echte Datei ins Workspace des Agenten (mycroft/jarvis) und gibt den Container-Pfad zurueck. Zielverzeichnis pro User in config.json unter mail_attachment_dirs (host + container Pfad; mycroft: /mnt/ssd/openclaw/mycroft/data/workspace/mail-attachments -> /home/node/.openclaw/workspace/mail-attachments). UID 1000 (stefan/node) identisch, keine Permissions-Probleme. Kollisionen bekommen Suffix (1). Sinn: Der Agent kann den Anhang mit seinen Datei-/Shell-Tools weiterverarbeiten, nicht nur inline ansehen.
    • read_mail/read_attachment/download_attachment Key-Fix (2026-09-09): Der FTS-Index speichert den vollen Maildir-Dateinamen inkl. Dovecot-Flags-Suffix (...:2,T), waehrend Python mailbox.Maildir als Key nur den Teil vor :2, nutzt. Dadurch schlug read_mail mit "Message not found" fehl, obwohl search_mail die Mail fand (betrifft alle Clients: OpenClaw + Hermes). Fix in server.py: _norm_key(key) schneidet das :2,...-Suffix ab und wird in read_mail, read_attachment, download_attachment angewandt. Backup: server.py.bak-maileade-20260909.
    • Nova .com voll in Betrieb (2026-09-10): imap_passwords.nova + IMAP_ACCOUNTS['nova'] (imap.1blu.de, user d370128_0-stefanlohmaier) ergaenzt. Verifiziert per Bearer per User: stefan sieht nur d370128_0-slohmaier (.de), nova nur d370128_0-stefanlohmaier (.com), kati nur akpolke@gmail.com. Real-Login gegen imap.1blu.de ok. Backups: config.json.bak-novacom-20260910-110015, server.py.bak-novacom-20260910-*.
    • create_draft Gmail-Quoting-Fix (2026-09-11): create_draft fuer Katis Gmail-Account schlug mit IMAP-Fehler: APPEND command error: BAD [b'Could not parse command'] fehl. Ursache: Python-imaplib quotet den Ordnernamen bei append()/select() mit Literal-Syntax ({n}) NICHT; Gmail bricht bei Ordnernamen mit Sonderzeichen ab (Drafts-Ordner [Google Mail]/Entw&APw-rfe enthaelt & und []). Fix: Helper _imap_quote_folder() in server.py, der Ordnernamen mit Sonderzeichen ( &[]\\") in doppelte Anführungszeichen setzt und beim append anwendet. 1blu-Accounts (stefan/nova, Drafts) bleiben unquotiert. Verifiziert: echter APPEND an Gmail-Drafts mit gequotetem Namen -> OK, Test-Draft danach wieder geloescht. Backup: server.py.bak-20260911-095326.
    • Account-Isolierung pro Agent (2026-09-09): server.py filtert die sichtbaren Mail-Accounts je User via Config mail_account_allow (config.json): stefan (mycroft/.de) -> nur d370128_0-slohmaier; nova (.com) -> nur d370128_0-stefanlohmaier. _discover_accounts wendet den Filter fuer alle Tools an (list/search/read/attachment). Fuer nova liegt der .com-Account als Symlink in /mnt/ssd/Backup/stefan/nova-imap/; index_maildirs.py/_discover_folders nutzen os.walk(..., followlinks=True), damit Volltext-Index und Ordner-Scan den Symlink durchlaufen. Config-Backup: config.json.bak-20260909.
    • Volltextindex (2026-09-03): search_mail nutzt einen SQLite-FTS5-Index statt des Maildir-Vollscans (der bei Katis Gmail-Archiv, 16 GB / ~30k Mails, das Gateway-Request-Timeout sprengte). Index-DBs: /var/lib/mail-index/<user>.sqlite (stefan, kati, nova, mcptest); Build/Update: /opt/mcp-servers/mail/index_maildirs.py, getaktet via mail-index.timer (alle 5 Min, versetzt zum mail-backup.timer). Such-Strategie: FTS5-Prefix-Treffer auf sender/to/subject/body; E-Mail-Adressen (mit @) ueber LIKE. Erst-Build bereit, wenn <user>.ready existiert; ohne ready faellt search_mail auf den alten Scan zurueck.
    • Ungelesene Mails im Maildir-new/ (2026-09-26): mbsync legt Gmail-Mails ohne \Seen-Flag in <folder>/new/ ab (nicht cur/). Index und _discover_folders sahen aber nur cur/ -> jede ungelesene Mail war fuer search_mail unsichtbar (kati 762, stefan 577, nova 960 zusaetzliche Mails; neueste zuerst betroffen). Fix: mailindex.py::update_user walkt jetzt cur und new; server.py::_discover_folders akzeptiert Ordner mit cur oder new. _parse_file/_norm_key waren bereits pfad-korrekt, read_mail funktionierte (Maildir vereint new+cur). Verifiziert per MCP-Call als kati (search_mail/read_mail auf eine neue new/-Mail), Index-Neuaufbau korrekt, test_smoke.py gruen und test_all.py+test_edge.py 96 passed. Backups: mailindex.py.bak-newdir-*, server.py.bak-newdir-*, kati.sqlite.bak-newdir-*.
  • Calendar + Tasks — list_calendars, get_events, search_events, list_task_lists, get_tasks, create_event (travel time + geocoding + reminders), create_task
    • Zeitzonen-Fix (2026-09-30): Timed-Events/Tasks wurden ohne TZID (floating) geschrieben; Baikal las sie als UTC, in der CalDAV-Suite +2h verschoben. Jetzt: naive Eingaben werden als Europe/Berlin lokalisiert (pytz), explizite Offsets/Z konvertiert. Betroffen waren alle per MCP angelegten Timed-Termine; per Einmal-Skript (alle stefan/kati-Kalender) auf TZID umgeschrieben. Anzeige normalisiert aware Zeiten nach Berlin. delete_event/update_event/delete_task/update_task loesen den echten Ressourcenpfad per UID auf (_find_href), da der .ics-Dateiname bei Importen (medatixx) nicht die UID ist (Delete lief sonst ins Leere, Update erzeugte Duplikate).
    • Auslands-Zeitzonen (2026-10-01): create/update_event + create/update_task haben ein timezone-Argument (IANA, Default Europe/Berlin). Fuer Termine im Ausland (z.B. Hongkong) timezone="Asia/Hong_Kong" setzen und die lokale Ortszeit eintragen; gespeichert wird TZID=Asia/Hong_Kong, die Ausgabe zeigt den passenden Offset (+08:00). Ungueltige Zonen liefern einen klaren Fehler. Naive Zeiten ohne timezone bleiben Europe/Berlin.
  • Contacts — search_contacts, get_contact (with photo), create_contact, set_contact_photo
  • Files — list_files, read_file (image/document/text), file_info, search_files, write_file, create_folder, delete_file, move_file
    • URL-Pfad-Encoding-Fix (2026-09-11): _dav() setzte User-Pfade roh in die WebDAV-URL. httpx encodiert Leerzeichen/Umlaute automatisch, aber # (wurde Fragment) und ? (wurde Query-Start) im Dateinamen zerlegten die URL; ein literales % erzeugte Ambiguitaet mit bereits-encodierten %XX-Sequenzen (oCIS liefert hrefs wie Entw%C3%BCrfe zurueck). Fix: _enc_path() in server.py encodiert #->%23, ?->%3F und % nur ausserhalb gueltiger %XX-Folgen (roundtrip-sicher). Anwendung zentral in _dav() -> wirkt auf alle 7 Datei-Tools. Verifiziert ueber mcptest-Account (Dateien mit #/%/?/Umlaut/Leerzeichen anlegen/lesen/loeschen) + neuer Edge-Test test_url_special_chars_roundtrip. Backup: files/server.py.bak-20260911-113635.
  • Notes — list_notebooks, list_notes, search_notes, read_note, create_note, list_note_resources, read_resource (attachments)
  • Ghostfolio — portfolio_details, get_performance, get_dividends, list_accounts, create_account, import_activities, list_activities, delete_activity (Portfolio-Tracker)
    • Kaltstart-Latenz (2026-09-11): Der erste MCP-Call nach laengerer Inaktivitaet kann 6-26 s dauern (Ghostfolio laedt dann historische Wechselkurse ueber ExchangeRateDataService, z.B. AUDEUR ab 2023, von externen Quellen). Warm sind Calls 0.6-1 s. Kein Bug -- der naechtliche Smoke-Test (05:00) lief in diesem Kaltfenster und ueberschritt das 60-s-Timeout. Test-Timeout fuer ghostfolio auf 180 s erhoeht (test_smoke.py).

owamail (BBS-Postfach, Port 5131)

Separater MCP-Server fuer Katis BBS-Arbeitsmail (Exchange 2019, S25-EXCHANGE, https://bbsbex.bbsb.org/owa/). Tools: login, list_folders, search_mail, read_mail, download_attachments (Anhaenge via GetFileAttachment ins jarvis-Workspace owa-attachments), create_draft (Entwurf im Drafts-Ordner, KEIN Senden).

  • Implementierung (2026-09-11): Nutzt den klassischen OWA-Formular-Login (POST /owa/auth.owa, Sperrschutz: GENAU EIN Login-Versuch, kein Retry -- Katis Arbeitspasswort darf nie durch Auto-Wiederholungen gesperrt werden) und die interne OWA-JSON-API: POST /owa/service.svc?action=&EP=1&ID=-1&AC=1 mit Action-Header, X-OWA-CANARY und Exchange-JSON-Payloads. API-Muster aus https://github.com/nhype/owa-exchange-mcp (MIT, Referenz unter /opt/mcp-servers/owamail/vendor/exchange_mcp/). Systemd mcp-owamail (Port 5131). EWS-Basic-Auth ist serverseitig deaktiviert (401), IMAP/POP3-Ports sind von aussen zu -- daher nur ueber die OWA-API. Nicht mit dem mail-Server (5100, Gmail/1blu) verwechseln. Zugriff: Katis Bearer (client_id kati) im jarvis-openclaw.json unter mcp.servers.owamail (http://172.26.0.1:5131/mcp). Nur User kati/mcptest duerfen die Tools (ALLOWED_USERS), andere Bearer werden abgewiesen.
  • Sicherheit: Credentials in /opt/mcp-servers/owamail/auth.txt (chmod 600). Der Server bindet nur an localhost; Zugriff ueber Bearer-Auth (OAuth client_credentials).
  • Gemeinsamer Client (2026-09-16): Login/API-Transport liegt in owamail/owa_client.py (Klasse OWAClient, Modul-Instanz client). server.py importiert daraus; der Kalender-Fetcher /opt/owa-kati-calendar/owa_fetch.py nutzt denselben Client (Einweg-Sync Katis Arbeitskalender -> Baikal "Arbeit", stuendlich). Aenderungen am Client betreffen beide -> mcp-owamail.service neu starten.
  • Vollständige Mail-Abdeckung (2026-09-11): search_mail unterstuetzt Offset-Paging (offset/limit, zeigt "Ordner hat N Mails; mehr vorhanden (Offset X)") -- damit erreicht Jarvis auch die aeltesten Mails eines Ordners (Inbox: ~3700+ bis 2023, Archiv: bis 2024). Zusaetzlich scan_all=true mit Suchbegriff: blaettert automatisch durch bis 2000 Mails und findet alte Treffer (z.B. Betriebsrats-Newsletter 2025), ohne manuelles Paging.

Setup

python3 -m venv venv
venv/bin/pip install mcp[cli] httpx vobject python-dateutil pytest
cp tokens.json.example tokens.json      # set OAuth client secrets
cp config.json.example config.json      # set backend credentials

Notes needs joplin-cli sync clients exposing the Data API (see /opt/joplin-mcp/).

Ghostfolio braucht das JWT-Token in /opt/ghostfolio/migration/.auth-token.

Usage with claude.ai

Settings → Integrations → Custom MCP Server:

  • URL: https://<service>.mcp.your-domain/mcp (mail, calendar, contacts, files, notes)
  • OAuth Client ID: your username (e.g. stefan)
  • OAuth Client Secret: from tokens.json

claude.ai runs the OAuth Authorization Code + PKCE flow automatically.

Tests

venv/bin/python -m pytest tests/test_all.py -v

54 integration tests (OAuth, all tools, CRUD in isolated test collections). Run daily via mcp-tests.timer.

Fix 2026-09-06: actualbudget-Test aus Smoke entfernt

Der Smoke-Test (test_smoke.py) und SERVERS in test_all.py referenzierten einen actualbudget-MCP-Server auf Port 5121, der nie existiert (kein Verzeichnis, keine systemd-Unit, kein Prozess — verworfen). Folge: der naechtliche mcp-tests.timer schlug jede Nacht mit 2 failed auf (aktualbudget-read + server_up), was die urgent-NTFY "MCP Smoke-Tests fehlgeschlagen" ausloeste. actualbudget aus SERVERS und test_actualbudget_read entfernt -> Smoke laeuft wieder gruen (12 passed). Backups: tests/test_all.py.bak-20260906, tests/test_smoke.py.bak-20260906.

Oeffentliche Endpunkte (2026-09-18)

Oeffentlich erreichbar (nginx -> 127.0.0.1:, Let's-Encrypt-SAN, Rate-Limit mcp_auth auf /authorize und /token):

Auth: OAuth + nicht-ablaufende Service-Tokens

  1. OAuth 2.0 Authorization Code + PKCE (claude.ai), client_id/secret aus tokens.json.
  2. Service-Tokens fuer Maschinen-Clients (opencode, Skripte), die einen statischen Authorization: Bearer-Header setzen. Ablage: service_tokens.json ({"<token>": {"user": "stefan", "label": "opencode-polo"}}), chmod 600. common.py prueft Service-Tokens in _resolve_access_token() vor den OAuth-Access-Tokens (konstanter Vergleich via secrets.compare_digest), sie laufen nie ab. Widerruf = rm. Verwaltung: ./mint-service-token.sh add <user> <label> | rm <label> | list.

Raw-Endpunkte (Rohdateien/Binaer, token-geschuetzt)

Fuer beliebige Binaerdateien/-groessen (ersetzen Direkt-Mounts/rclone). Auth ueber dieselbe BearerAuthMiddleware (Service-Token oder OAuth), kein anonymer Zugriff:

  • files: GET /raw?path=<ocis> (Download, gestreamt) und PUT /raw?path=<ocis> (Upload, Body = Rohbytes)
  • mail: GET /raw?account=&folder=&key=&index= (roher Anhang, Content-Disposition)
  • notes: GET /raw?resource_id=<id> (roher Resource); Upload/Ersetzen: PUT /raw?note_id=<id>&filename=<name> (neue Resource anlegen + in Notiz verlinken) bzw. PUT /raw?resource_id=<id> (vorhandene ersetzen)
  • contacts: GET /raw?uid=<uid> (Kontaktfoto roh) und PUT /raw?uid=<uid>[&type=jpeg|png|gif] (Foto aus Rohbytes setzen/ersetzen)

Beispiel Download: curl -H "Authorization: Bearer $TOKEN" "https://files.mcp.slohmaier.de/raw?path=/x.pdf" -o /tmp/x.pdf Beispiel Upload: curl -X PUT -H "Authorization: Bearer $TOKEN" --data-binary @/tmp/x.pdf "https://files.mcp.slohmaier.de/raw?path=/Ziel/x.pdf"

Limits: nginx client_max_body_size 5g (Uploads), notes MAX_ATTACHMENT_BYTES 2GB. Downloads gestreamt (kein Body-Limit).

OpenClaw (mycroft/jarvis)

Alle MCP-Server (notes, calendar, mail, contacts, files, openwearables, owamail) in /mnt/ssd/openclaw/<agent>/data/openclaw.json zeigen seit 2026-09-18 auf die oeffentlichen URLs; Bearer ist ein nicht-ablaufendes Service-Token (${MCP_BEARER}, Labels openclaw-mycroft/jarvis/nova). ghostfolio wurde entfernt. Bewusste Abweichung von der AGENTS-Regel "lokale Routen", damit die Config bei einem Umzug (z. B. nach Odin) unveraendert bleibt. Verifiziert: beide Container erreichen alle oeffentlichen Endpunkte mit HTTP 200.

Monitoring

Der naechtliche Smoke (mcp-tests.timer 05:00) prueft die oeffentliche Route mit tests/test_public_smoke.py: pro Server ohne Token 401, mit Service-Token (Label smoketest) initialize + tools/list ueber https://<name>.mcp.slohmaier.de/mcp. Faengt DNS-, vhost-, TLS-/Cert- und Auth-Ausfaelle ab (der interne Smoke testet nur 127.0.0.1:<port>).

Zukunfts-Option: OAuth/DCR fuer ChatGPT & spec-konforme Clients

Service-Tokens funktionieren nur bei Clients, die einen eigenen Header setzen koennen (opencode, OpenAI-Responses-API ueber das authorization-Feld, Cursor, mcp-remote usw.). Die ChatGPT-App-Connectoren und strikt spec-konforme OAuth-Clients koennen das nicht; sie brauchen OAuth mit Dynamic Client Registration. Dafuer waeren noetig:

  • registration_endpoint (POST /register, RFC 7591) im AS-Metadata (common.py)
  • /.well-known/oauth-protected-resource (RFC 9728) + passendes WWW-Authenticate
  • Redirect-Allowlist in oauth_authorize() ueber claude.ai hinaus erweitern (ChatGPT-Callback)
  • Consent-Schritt (aktuell Auto-Approve)
  • Audience-/resource-Pruefung (RFC 8707)

Service-Tokens koennen parallel bestehen bleiben (Bearer-Middleware akzeptiert beides).

License

MIT

S
Description
Self-hosted MCP servers for Claude — Mail, Calendar, Contacts, Files, Notes via CalDAV/CardDAV/WebDAV/IMAP
Readme
727 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 98.5%
Shell 1.5%