Self-hosted [MCP](https://modelcontextprotocol.io) 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/.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 `.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 `/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). - **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 ```bash 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://.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 ```bash 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`): - https://notes.mcp.slohmaier.de/mcp (Notes, 5104) - https://calendar.mcp.slohmaier.de/mcp (Calendar, 5101) - https://mail.mcp.slohmaier.de/mcp (Mail, 5100; deckt auch den nova/.com-Bearer ab) - https://contacts.mcp.slohmaier.de/mcp (Contacts, 5102) - https://files.mcp.slohmaier.de/mcp (Files, 5103) - https://openwearables.mcp.slohmaier.de/mcp (OpenWearables, 5105) - https://owamail.mcp.slohmaier.de/mcp (OWA Mail, 5131; nur kati/mcptest) - DNS: Wildcard `*.mcp.slohmaier.de` (1blu) -> home.slohmaier.de -> poloschwabing.home64.de - Cert: zentrales `akpo.slohmaier.de` (SAN-Liste, HTTP-01 webroot). Neue Hosts dort ergaenzen: `certbot certonly --webroot -w /var/www/html --cert-name akpo.slohmaier.de --expand -d -d ` - nginx: `/etc/nginx/sites-available/.mcp.slohmaier.de` (Symlink in sites-enabled) - iptables unveraendert: nginx erreicht die Ports via 127.0.0.1 (ACCEPT-Regel), kein direkter Port. - **Ghostfolio-MCP (5120) am 2026-09-18 entfernt** (0 Tool-Calls in 7 Tagen; vhost deaktiviert, unit disabled). Portfolio weiter ueber die REST-API `https://portfolio.slohmaier.de`. ### 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` (`{"": {"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