Skip to main content
Glama
homelab-mcp-hub

homelab-mcp-hub

by doemefu

homelab-mcp-hub

A read-only remote MCP server for mail and calendars, part of the doemefu homelab (Epic doemefu/homelab#168).

The hub is a pure OAuth resource server: the homelab's auth-service issues the access tokens, the hub validates them offline against the auth-service JWKS and serves MCP tools over Streamable HTTP. Claude connects to it as a custom connector.

Contract: spec docs/080-mcp-hub.md and ADR docs/adr/0003-mcp-hub-authorization.md in the doemefu/homelab repository (published there with doemefu/homelab#182). This repository links to them and carries no copy.

Status

Milestone 1 (#170): iCloud mail and calendar live at mcp.furchert.ch. outlook mail live since 2026-10-06 (#171), gmail mail live since 2026-10-07 (#172, configuration only). Calendars of other accounts are served through iCloud. Mail history part a (list_messages, cursors, get_message by ref) live since 2026-10-22 (WP13a, #44). get_message_status merged 2026-10-22 (WP13b, #44), get_thread live since 2026-10-23 (WP13c) and search_messages live since 2026-10-27 (WP13d, PR #74); story #44 is done.

Work package

Scope

Status

WP5a

Repository bootstrap, authorization layer, list_accounts, image, CI, k8s/

Done

WP5b

IMAP adapter, list_unread, get_message, sanitiser, output budget, provider CI job

Done

WP5c

CalDAV adapter, get_events, background status check

Done

WP5d

Metrics and alerts on the internal port (search_messages is WP13d)

Planned

WP13a

Mail history part a: list_messages, extended summaries, cursors, get_message by ref (story #44)

Done (merged and live 2026-10-22)

WP13b

Mail history part b: get_message_status (story #44)

Done (merged 2026-10-22, live)

WP13c

Mail history part c: get_thread with quote removal and the subject fallback (story #44)

Done (merged and live 2026-10-23)

WP13d

Mail history part d: search_messages by words, sender, recipient and subject (story #44)

Done (merged and live 2026-10-27)

WP9

Microsoft Graph for outlook: token store, mcp-hub login, mail adapter, mcp-hub check-registry

Done (live)

WP8

gmail mail over the existing IMAP adapter (registry entry and credentials only)

Done (live)

WP10

Further accounts (calendar feed)

Planned

Related MCP server: Postroom

Quick reference

Item

Value

MCP endpoint

https://mcp.furchert.ch/mcp (container port 8083; the only port behind the Cloudflare Tunnel)

Protected-resource metadata

/.well-known/oauth-protected-resource/mcp on port 8083

Health and metrics

/healthz, /readyz, /metrics (Prometheus text, spec 080 §9.7) on port 8084 (cluster-internal)

Protocol versions

2026-07-28 (stateless) and 2025-11-25 (initialize handshake)

Scopes

mail:read calendar:read (both required)

Image

ghcr.io/doemefu/homelab-mcp-hub:main-<UTC timestamp> (linux/amd64 + linux/arm64)

Tools

list_accounts, list_unread, list_messages, get_message, get_message_status, get_thread, search_messages, get_events (all read-only); mail over IMAP or Microsoft Graph (outlook), calendars over CalDAV

Stack

Python 3.13, mcp 2.3.0, uvicorn, starlette, pydantic, PyJWT, IMAPClient, icalendar, recurring-ical-events

Deployment

Flux from k8s/ into namespace apps (see DEPLOYMENT.md)

Build and test

uv sync --locked
uv run ruff check && uv run ruff format --check
uv run mypy --strict src
uv run pytest -m "not provider"    # unit, contract (gate G6) and integration tests
# provider tests against local GreenMail, Radicale and PostgreSQL containers (see CONTRIBUTING.md)
scripts/provider_services.sh up && HUB_PROVIDER_TESTS=1 uv run pytest -m provider; scripts/provider_services.sh down

Run locally

docker build -t mcp-hub:dev .
scripts/smoke_image.sh mcp-hub:dev   # starts the image read-only as uid 10001, checks 401/200/403/421 and the HTML converter

scripts/smoke_image.sh generates a throwaway signing key, a JWKS and a secrets directory with the example registry, so no real credentials are involved.

Development

See CONTRIBUTING.md for prerequisites, the local environment, the test suites and the review process.

Documentation

File

Covers

INTERFACES.md

MCP endpoint, authorization rules, tools, configuration, logging

DEPLOYMENT.md

Manifests, image, bootstrap sequence, operations, troubleshooting

CONTRIBUTING.md

Local development, tests, process

CHANGELOG.md

Changes per release

CLAUDE.md

Conventions for Claude Code sessions

Licence

MIT, see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Self-hosted MCP connector for Claude.ai that provides multi-account IMAP/SMTP email management via OAuth 2.1 + DCR + PKCE shim and an admin backoffice.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      A self-hosted remote MCP server that gives AI assistants read, organize and optional send access to mail, calendars, tasks and contacts across many IMAP, Gmail, CalDAV, CardDAV and Google accounts behind one authenticated endpoint.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides an OAuth 2.1 authorization and login layer plus tool registration for MCP connectors, so a connector can be added to Claude clients with only a URL and password. It also shapes tool names, descriptions and input schemas for what Claude clients actually display, returning compact results and readable error messages.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude and other MCP clients to search, read, organize, and draft replies for mail in a self-hosted MailFlow instance via its HTTP API and scoped API tokens. It can mark, star, archive, snooze, categorize, move messages except into Trash or Junk, and save drafts, but cannot send or delete mail.
      MIT