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.jsonuntermail_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 Pythonmailbox.Maildirals Key nur den Teil vor:2,nutzt. Dadurch schlugread_mailmit "Message not found" fehl, obwohlsearch_maildie Mail fand (betrifft alle Clients: OpenClaw + Hermes). Fix inserver.py:_norm_key(key)schneidet das:2,...-Suffix ab und wird inread_mail,read_attachment,download_attachmentangewandt. Backup:server.py.bak-maileade-20260909. - Nova .com voll in Betrieb (2026-09-10):
imap_passwords.nova+IMAP_ACCOUNTS['nova'](imap.1blu.de, userd370128_0-stefanlohmaier) ergaenzt. Verifiziert per Bearer per User:stefansieht nurd370128_0-slohmaier(.de),novanurd370128_0-stefanlohmaier(.com),katinurakpolke@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_draftfuer Katis Gmail-Account schlug mitIMAP-Fehler: APPEND command error: BAD [b'Could not parse command']fehl. Ursache: Python-imaplib quotet den Ordnernamen beiappend()/select()mit Literal-Syntax ({n}) NICHT; Gmail bricht bei Ordnernamen mit Sonderzeichen ab (Drafts-Ordner[Google Mail]/Entw&APw-rfeenthaelt&und[]). Fix: Helper_imap_quote_folder()inserver.py, der Ordnernamen mit Sonderzeichen (&[]\\") in doppelte Anführungszeichen setzt und beimappendanwendet. 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.pyfiltert die sichtbaren Mail-Accounts je User via Configmail_account_allow(config.json):stefan(mycroft/.de) -> nurd370128_0-slohmaier;nova(.com) -> nurd370128_0-stefanlohmaier._discover_accountswendet 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_foldersnutzenos.walk(..., followlinks=True), damit Volltext-Index und Ordner-Scan den Symlink durchlaufen. Config-Backup:config.json.bak-20260909. - Volltextindex (2026-09-03):
search_mailnutzt 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 viamail-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>.readyexistiert; ohne ready faelltsearch_mailauf den alten Scan zurueck. - Ungelesene Mails im Maildir-
new/(2026-09-26): mbsync legt Gmail-Mails ohne\Seen-Flag in<folder>/new/ab (nichtcur/). Index und_discover_folderssahen aber nurcur/-> jede ungelesene Mail war fuersearch_mailunsichtbar (kati 762, stefan 577, nova 960 zusaetzliche Mails; neueste zuerst betroffen). Fix:mailindex.py::update_userwalkt jetztcurundnew;server.py::_discover_foldersakzeptiert Ordner mitcurodernew._parse_file/_norm_keywaren bereits pfad-korrekt,read_mailfunktionierte (Maildir vereint new+cur). Verifiziert per MCP-Call als kati (search_mail/read_mailauf eine neuenew/-Mail), Index-Neuaufbau korrekt,test_smoke.pygruen undtest_all.py+test_edge.py96 passed. Backups:mailindex.py.bak-newdir-*,server.py.bak-newdir-*,kati.sqlite.bak-newdir-*.
- 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
- 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/Berlinlokalisiert (pytz), explizite Offsets/Zkonvertiert. 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_taskloesen 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).
- 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
- 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 wieEntw%C3%BCrfezurueck). Fix:_enc_path()inserver.pyencodiert#->%23,?->%3Fund%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-Testtest_url_special_chars_roundtrip. Backup:files/server.py.bak-20260911-113635.
- URL-Pfad-Encoding-Fix (2026-09-11):
- 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).
- Kaltstart-Latenz (2026-09-11): Der erste MCP-Call nach laengerer Inaktivitaet kann 6-26 s dauern (Ghostfolio laedt dann historische Wechselkurse ueber
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_idkati) im jarvis-openclaw.json untermcp.servers.owamail(http://172.26.0.1:5131/mcp). Nur Userkati/mcptestduerfen 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(KlasseOWAClient, Modul-Instanzclient).server.pyimportiert daraus; der Kalender-Fetcher/opt/owa-kati-calendar/owa_fetch.pynutzt denselben Client (Einweg-Sync Katis Arbeitskalender -> Baikal "Arbeit", stuendlich). Aenderungen am Client betreffen beide ->mcp-owamail.serviceneu starten. - Vollständige Mail-Abdeckung (2026-09-11):
search_mailunterstuetzt 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). Zusaetzlichscan_all=truemit 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):
-
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 <alle> -d <neu> -
nginx:
/etc/nginx/sites-available/<name>.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
- OAuth 2.0 Authorization Code + PKCE (claude.ai), client_id/secret aus
tokens.json. - 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.pyprueft Service-Tokens in_resolve_access_token()vor den OAuth-Access-Tokens (konstanter Vergleich viasecrets.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) undPUT /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) undPUT /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) + passendesWWW-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