mailhub-mcp

Install mailhub-mcp

Setup takes some care. The tutorial walks through every step; this is the outline.

You will need

  • A Google account to create a Google Cloud project
  • A Linux machine with Docker
  • A public HTTPS address for it

mailhub-mcp is beta software. Pin a release with MAILHUB_VERSION so updates happen when you choose.

Install

  1. Create a Google Cloud project

    Enable the Gmail API and create one OAuth client of type Web application. Its authorized redirect URIs are the connector login, <PUBLIC_BASE_URL>/auth/callback, plus two for the admin page:

    <PUBLIC_BASE_URL>/admin/auth/callback
    <PUBLIC_BASE_URL>/admin/oauth/callback
  2. Configure .env

    Copy .env.example and set your public URL, the Google client ID and secret, your own login in ALLOWED_EMAILS and a signing key.

  3. Start the container

    This pulls ghcr.io/trainedloop/mailhub-mcp and listens on 127.0.0.1:8742.

    docker compose up -d
  4. Put HTTPS in front

    Any reverse proxy or tunnel with TLS at the root of a host name, such as https://mail.example.com. The Tailscale Funnel example is a complete home-server setup, including a firewall that isolates the container. The Tailscale sidecar example gives the server its own host name and publishes no port on the host.

  5. Add the connector

    In claude.ai: Settings, Connectors, Add custom connector, with https://mail.example.com/mcp. Sign in with the Google login from ALLOWED_EMAILS.

Works with MCP clients that support remote servers

What a client needs:

  • a remote MCP server over streamable HTTP, at https://mail.example.com/mcp;
  • OAuth 2.1 with PKCE and dynamic client registration;
  • its OAuth callback URL added to ALLOWED_REDIRECT_URIS in .env (Claude's callbacks are there by default).
Client support status
ClientStatusNotes
Claude Tested As a custom connector in claude.ai, on the web and in the mobile app.
Online assistants with remote MCP support, such as ChatGPT Should work, untested Designed for any client that meets the requirements above. Add the client's callback URL and connect to /mcp. Reports are welcome.
Local models, through an MCP client that runs them on your machine Should work, untested Email content then never goes to an AI provider: the model, the client and the server are all yours. The server still needs internet access to reach Gmail; "offline" refers to the model. Loopback callbacks (http://localhost) are accepted.

mailhub-mcp is an independent open-source project, not affiliated with Anthropic, OpenAI or Google. Setup for other clients: Connecting other MCP clients.

Built for inbox triage

MCP (Model Context Protocol) is how AI assistants call outside tools. mailhub-mcp is a remote MCP server: your assistant connects to it over HTTPS, you log in with Google, and the assistant gets a set of mail tools.

Ask what came in overnight, which senders flood your inbox, or to file last month's receipts under a label. It reads, reports and proposes; changes to many messages are previewed first and applied only when you confirm.

18 tools: 11 read-only, 7 that change something. Three ready-made prompts: daily_triage, clean_newsletters, organize_inbox.

Read
search_emails, read_email, read_thread, inbox_overview with unread counts, categories and top senders, count_messages to size a change before making it. Attachments come with a download link that opens only after you sign in to /admin.
Bills
Read results carry what a bill asks you to pay: the bank slip line or PIX code, checked against its check digits, with the amount and due date. They are read from the body and from the bill's PDFs, including ones protected with part of your CPF or CNPJ.
Organize
Add or remove labels, archive, mark read, star, by message or by search query. Each batch is journaled and can be reverted.
Draft
Leave a reply draft in the thread for you to review and send yourself.
Remember
Triage preferences (important and ignored senders or keywords, time of the last triage) keep a daily routine consistent from one run to the next.

One server, every mailbox you own

Link your personal, work and side-project mailboxes to the same instance. Each gets a short alias, and the read tools search all of them at once by default, so one question covers every inbox.

If one mailbox fails (an expired credential, a rate limit), the others still answer: results come back with at most one error per account.

  • alice-personalGmail
  • alice-workGoogle Workspace
  • alice-side-projectGmail

Example aliases. Aliases are lowercase letters, digits and hyphens. Gmail is the provider available today; Outlook and IMAP are ideas on the roadmap.

Runs on your machine, in Docker

A home server, a small VPS or any Linux box with Docker. Your OAuth tokens, change journal and preferences live in folders on that machine. Apart from the Google APIs, the server sends nothing anywhere.

Published image
ghcr.io/trainedloop/mailhub-mcp for linux/amd64 and linux/arm64. Pin a release with MAILHUB_VERSION so updates happen when you choose.
Locked-down container
Read-only filesystem, all capabilities dropped, a memory limit, and the port bound to 127.0.0.1 only. You put HTTPS in front of it.
Health
GET /health for Docker's health check, and mailhub-admin accounts to check that every linked mailbox still answers.
  1. Your MCP clientfor example claude.ai on the web or phone
  2. HTTPS + Google loginmailhub-mcp on your serverhttps://mail.example.com, tokens and journal on local disk
  3. Gmail APIYour mailboxesalice-personal, alice-work, alice-side-project

What the assistant reads becomes part of your conversation, so it is sent to the provider of the model you use. That is also why a model you run yourself is interesting; see clients.

What you can use it for

  • A daily triage report across every inbox

    Mail since the last triage, grouped into needs attention, can wait and suspicious, with your important senders first. Triage only reads; it never changes mail.

    Prompt daily_triage

  • Cleaning up newsletters

    See the senders that fill your inbox, with their unsubscribe link for you to decide on, then archive their mail after reviewing a preview.

    Prompt clean_newsletters, tools inbox_overview, modify_by_query

  • Organizing a messy inbox with labels

    The assistant proposes a few labels and which mail belongs in each. You approve, it applies. If the result is wrong, undo it.

    Prompt organize_inbox, tools create_label, undo_change, undo_since

  • Scheduled triage routines

    Run triage every morning as a scheduled task in your MCP client. Stored preferences and the time of the last run keep each report consistent.

    Tools get_preferences, set_preferences; TOOLS=read-only for report-only routines

  • Bills to pay

    "What is due this week?" Bills come back with amount, due date and payment code, also when those are only in a password-protected PDF. With a finance connector in the same session, the assistant can also tell which ones are already paid.

    The billing field of read_email, read_emails, read_thread

  • Asking about your mail from your phone

    "Did the plumber reply?" "Anything from school this week?" Ask from your MCP client's mobile app and get an answer that covers every account.

    Tools search_emails, read_thread

Contribute

Issues and pull requests

Bug reports, setup friction, reports from clients other than Claude, and fixes are welcome on GitHub issues and pull requests.

Development setup

Python with uv:

uv sync
uv run pytest -q

Add a mail provider

Providers implement a small MailProvider interface and pass a shared contract test suite. Outlook (Microsoft Graph) and IMAP are on the roadmap. Start with the architecture doc and its adding a provider section.

Security reports

Please report vulnerabilities privately through the repository's Security tab (private vulnerability reporting), not in a public issue. Prompt-injection and sanitizer bypasses are in scope. See SECURITY.md and the safety model.