Skip to main content
Glama
doemefu

homelab-mcp-hub

by doemefu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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).

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_mail moved to 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)

In review

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: charity-gmail-mcp

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

/healthz, /readyz 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, get_events (all read-only); mail over IMAP or Microsoft Graph (outlook), calendars over CalDAV

Stack

Python 3.13, mcp 2.2.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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • charity-gmail-mcp

    IgnatRU
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables accessing Gmail tools (search, read, draft) for a specific Google account via MCP, designed as a custom connector for Claude/Cowork to use alongside a different Google account.
    -

  • MCP Mail

    storesace-cv
    F
    license
    Not graded
    quality
    B
    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.
    -

  • Postroom

    vaclav-kozak
    A
    license
    Not graded
    quality
    A
    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