mcp-home/CLAUDE.md

mcp-home

Self-hosted MCP (Model Context Protocol) servers for Claude. Provides access to personal data services via remote HTTP endpoints with OAuth (Authorization Code + PKCE, and client_credentials).

Architecture

5 independent MCP servers, each on its own subdomain + port:

• Mail (mail.mcp.home.slohmaier.de, Port 5100) — searches IMAP backup Maildirs, reads attachments, creates drafts
• Calendar (calendar.mcp.home.slohmaier.de, Port 5101) — CalDAV against Radicale (events + tasks/reminders, travel time, geocoding, alarms)
• Contacts (contacts.mcp.home.slohmaier.de, Port 5102) — CardDAV against Radicale (contacts + photos)
• Files (files.mcp.home.slohmaier.de, Port 5103) — WebDAV against oCIS (full CRUD, images inline, documents as blobs)
• Notes (notes.mcp.home.slohmaier.de, Port 5104) — Joplin Data API (notes + attachments)

Each subdomain is its own nginx vhost proxying to the local port. 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 (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: Radicale CalDAV/CardDAV on 127.0.0.1:5232. Note: Radicale uses default DAV: namespace (no d: prefix) and CR: for CardDAV — regex must match both.
• 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).

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
• 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
• tests/test_all.py — 54 integration tests (pytest), daily via mcp-tests.timer

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). Each subdomain is an nginx vhost with rate-limited /authorize + /token. TLS via Certbot (shared cert on mail.mcp...). Joplin: joplin-cli-{stefan,kati}.service + joplin-sync.timer (15 min).

Content Types (returning binary)

• Text → TextContent
• Images (jpg/png/gif/webp) → ImageContent (base64 inline)
• Documents (PDF, docx, xlsx) / other binary → EmbeddedResource with BlobResourceContents (base64 + mimeType) — claude.ai processes these client-side

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. nginx vhost <name>.mcp.home.slohmaier.de + Certbot
4. systemd unit mcp-<name>.service
5. Backend creds in config.json
6. Tests in tests/test_all.py, update dashboard + this file

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