Skip to main content
Glama
Mailbox.org MCP Server

Mailbox.org MCP Server

by soenkenils

Mailbox.org MCP Server

A Model Context Protocol (MCP) server that integrates mailbox.org email, calendar and Sieve mail filters with Claude. It runs in either of two modes:

  • stdio (default): launched locally by Claude Desktop or Claude Code; your credentials and mail never leave your machine except to talk to mailbox.org.

  • http: a Streamable HTTP server you host yourself, reachable from Claude Code, claude.ai and mobile. See Hosted Mode.

Features

Email Integration (IMAP & SMTP)

Reading & Search:

  • ✅ Search emails by text content, sender, subject, date range, and message flags (read/unread, flagged, answered, draft, deleted)

  • ✅ Retrieve complete email content including headers, body, and attachments

  • ✅ Email thread management with conversation grouping

  • ✅ Folder browsing and navigation (INBOX, Sent, Drafts, etc.)

  • ✅ Attachment detection and metadata extraction

Composition & Management:

  • ✅ Send emails as plain text, HTML or both (sending attachments is not supported)

  • ✅ Save drafts to the Drafts folder without sending them

  • ✅ Email organization - move emails between folders

  • ✅ Flag management - mark as read/unread, important, etc.

  • ✅ Email deletion - trash or permanent removal

Performance:

  • ✅ Connection pooling for SMTP and IMAP with health monitoring

  • ✅ Session-based caching for improved performance

Calendar Integration (CalDAV)

  • ✅ Retrieve calendar events within specified date ranges

  • ✅ Search calendar events by title, description, location

  • ✅ Free/busy time checking for scheduling

  • ✅ Create, update and delete calendar events (timed or all-day, with attendees), without sending invitations unless you ask

  • ✅ Multi-calendar support and aggregation

  • ✅ Recurring events expanded into occurrences, with exception handling

  • ✅ Circuit breaker on CalDAV requests, backing off after repeated failures

  • ✅ Session-based caching for improved performance

Email Filter Management (Sieve/ManageSieve)

  • ✅ List and retrieve existing Sieve filter scripts

  • ✅ Create and update email filtering rules with Sieve syntax

  • ✅ Activate/deactivate filter scripts

  • ✅ Delete unwanted filter scripts

  • ✅ Syntax validation before deploying filters

  • ✅ Server capabilities discovery for supported Sieve extensions

Related MCP server: email-mcp

Requirements

  • Node.js 20 or later to run the server, and bun to install, build and test it

  • A mailbox.org account; an app password is recommended over your account password, so this server's access can be revoked on its own

  • At least one MCP client: Claude Desktop or Claude Code (stdio), or Claude Code / claude.ai against a hosted server (see Hosted Mode)

Installation

  1. Clone and build the project:

    git clone https://github.com/soenkenils/mailbox-mcp-server.git
    cd mailbox-mcp-server
    bun install
    bun run build
  2. Copy the example environment file and update it with your credentials:

    cp .env.example .env

    Note: For security, it's recommended to use an App Password instead of your main account password.

  3. Edit the .env file with your mailbox.org credentials:

    # Required settings
    MAILBOX_EMAIL=your-email@mailbox.org
    MAILBOX_PASSWORD=your-app-specific-password
    
    # Optional: IMAP configuration (defaults shown)
    MAILBOX_IMAP_HOST=imap.mailbox.org
    MAILBOX_IMAP_PORT=993
    MAILBOX_IMAP_SECURE=true
    
    # Optional: SMTP configuration (defaults shown)
    MAILBOX_SMTP_HOST=smtp.mailbox.org
    MAILBOX_SMTP_PORT=465
    MAILBOX_SMTP_SECURE=true
    
    # Optional: CalDAV configuration (defaults shown)
    MAILBOX_CALDAV_URL=https://dav.mailbox.org/
    
    # Optional: ManageSieve configuration (defaults shown)
    MAILBOX_SIEVE_HOST=imap.mailbox.org
    MAILBOX_SIEVE_PORT=4190
    MAILBOX_SIEVE_SECURE=false
    
    # Optional: Enable debug logging
    DEBUG=false

    Note: The server reads its configuration from environment variables only; it does not load .env itself. Bun loads .env from the working directory when it runs the code (bun src/main.ts, bun dist/main.js); node needs node --env-file=.env dist/main.js. In Claude Desktop, set the variables in the server's env block instead.

  4. Add to Claude Desktop configuration:

    Add this server to your Claude Desktop claude_desktop_config.json. Claude Desktop does not read .env, so the credentials go in the env block:

    {
      "mcpServers": {
        "mailbox-mcp-server": {
          "command": "node",
          "args": ["/path/to/mailbox-mcp-server/dist/main.js"],
          "env": {
            "MAILBOX_EMAIL": "your-email@mailbox.org",
            "MAILBOX_PASSWORD": "your-app-specific-password"
          }
        }
      }
    }

Available Tools

Every tool carries MCP tool annotations: a human-readable title plus hints that tell the client whether the tool only reads (readOnlyHint), can destroy data (destructiveHint), is safe to repeat (idempotentHint) and reaches outside your mailbox (openWorldHint). Clients use them to decide what to run freely and what to confirm with you first. The "Hints" column below summarises them for email and Sieve; the calendar reads (get_calendar_events, search_calendar, get_free_busy) are read-only, create_calendar_event is additive, update_calendar_event and delete_calendar_event are destructive, and all three calendar writes are open-world because they can email participants when asked to.

Each input schema is closed (additionalProperties: false). Undeclared arguments are ignored: they are dropped before validation, never reach the mail, calendar or Sieve server, and only their names are logged at debug level. Declared arguments are validated as before. update_calendar_event and delete_calendar_event are the exception and refuse undeclared arguments, so an edit is never reported for a field that was not applied.

Email Tools

Tool

What it does

Hints

Typed output

search_emails

Search one folder, newest first. query matches subject or body; from:address / to:address match a sender or recipient; the word OR (any case) between spaces separates alternatives, e.g. from:alice@example.com OR invoice; a phrase in double quotes is searched literally, OR and from: included ("rock or roll"). Optional since/before dates and the flag filters seen, answered, flagged, draft, deleted (true = only with the flag, false = only without, omit = both) narrow the whole query. Returns headers with flags; limit (1-200, default 50) and offset page through the matches, and the result says how many matched and which offset comes next

read-only

messages (each with flags and unread), total, nextOffset while pages remain

get_email

One message in full by UID, with attachment metadata. UIDs are per folder

read-only

found, message (headers, cc, body, attachments)

get_email_thread

Every message in a conversation, found by the Message-ID of any message in it; bodies are shortened to 200 characters

read-only

found, subject, participants, lastActivity, messages (uid, preview, truncated)

get_folders

Every folder with its path, flags and special-use role

read-only

folders

send_email

Send a message over SMTP immediately; needs text or html. Line breaks in text are kept; subjects and display names are single-line

destructive, open-world

success, messageId

create_draft

Save a message to Drafts (or another folder) without sending it; the body may be empty. The draft is built like sent mail: your account as sender, encoded headers, text and HTML both kept, Bcc remembered

additive

success, uid, folder

move_email

Move one message to another folder (it gets a new UID there)

idempotent

–

mark_email

Add or remove flags: \Seen, \Answered, \Flagged, \Deleted, \Draft (server keywords such as \Junk are accepted too; \Recent is refused, the server owns it)

idempotent

–

delete_email

Move one message to the trash, or with permanent: true expunge it (needs a server with UIDPLUS). Without a trash folder a non-permanent delete only flags the message \Deleted

destructive

–

create_directory

Create a folder, optionally under an existing parentPath

additive

–

Mail content in tool results is third-party data. search_emails, get_email and get_email_thread say so at the top of their text, and each message body is fenced between --- BEGIN EMAIL BODY <marker> --- and --- END EMAIL BODY <marker> --- lines with a random marker, so a message cannot pass itself off as instructions by closing the fence early.

Typed output. The tools with a "Typed output" entry return structuredContent that matches the outputSchema they declare, next to the same text as before, so a client can read a UID or the next offset without parsing prose. Fields that carry mail content (subjects, display names, bodies, previews, attachment names) are described in the schema as untrusted third-party data. A message that does not exist is found: false. A message date is its Date: header, else the server's arrival date; when neither is usable it is null ("unknown date" in the text) rather than a made-up one. Tools that only acknowledge an action report it through isError.

Calendar Tools

  • get_calendar_events - Retrieve events in a date range (default: today to 30 days later; limit 1-500, default 100, and offset page through them). Recurring events are listed once per occurrence; each event shows its UID, and an occurrence of a series shows the series UID plus an Occurrence: line with its recurrence id

  • search_calendar - Search events by keyword in title, description and location (same event format; default range today to one year later, limit 1-200, default 50)

  • get_free_busy - Check availability between a required start and end

  • create_calendar_event - Create an event (summary, start/end, optional description, location, all-day flag, attendees, target calendar) and return its UID. Timed events need a date-time with an explicit offset or Z (a date-time without one is read in the time zone of the machine running the server) and are stored in UTC. For all-day events pass dates (YYYY-MM-DD); end is the last day, inclusive, and can be omitted for a one-day event. Impossible dates such as 2025-02-30 and local times skipped by a daylight-saving change are refused. By default nobody is notified: attendees are only recorded on the event. Only with sendInvitations: true (meant for when you explicitly ask to invite people) does your account become the organizer, and mailbox.org may then email invitations to all attendees. The target calendar and the MAILBOX_CALENDARS entries are matched exactly, by display name, full URL or last URL segment; a name that matches several calendars is refused. When MAILBOX_CALENDARS is set, events can only be created in those calendars, and the first one listed is the default

  • update_calendar_event - Change an event found by its UID: only the fields passed change (an empty description or location removes it, attendees replaces the list and keeps the reply status of those who stay); alarms, recurrence rules and time zones are kept. Times follow the create_calendar_event contract; when only start is passed the event keeps its length, and values equal to the stored ones count as no change. The write carries the event's ETag (If-Match), so a change made elsewhere in the meantime fails with "changed on the server" instead of being overwritten

  • delete_calendar_event - Permanently delete an event found by its UID, also with If-Match

Recurring events. Update and delete act on the whole series and take the series UID. Changing or deleting a single occurrence is not supported: an occurrence id from the read tools (UID:2025-06-20 or UID:2025-06-20T08:00:00.000Z) is refused with a message naming the series UID (a stored event whose UID merely looks like that, e.g. holiday:2025-12-25, is found and changed as usual). Moving a recurring series (start, end, all-day) is refused as well, because times are written in UTC and the series would shift across daylight-saving changes; title, description, location and attendees can be changed.

No surprise mail (RFC 6638). mailbox.org sends scheduling mail for events that have an organizer and attendees. These tools avoid that unless you ask for it:

  • update_calendar_event records new attendees only (SCHEDULE-AGENT=CLIENT, no organizer added). With sendInvitations: true your account becomes the organizer and the server may email invitations, updates and cancellations.

  • A meeting you organize (organizer is your address, or one of the calendar user addresses the server reports, with attendees that are not marked SCHEDULE-AGENT=CLIENT) is not changed without sendInvitations: true and not deleted without notifyParticipants: true, since any change makes the server email the attendees.

  • An event is treated as an invitation you received only when your address is among its attendees and the organizer is someone else. Such an event cannot be changed; deleting it sends Schedule-Reply: F, asking the server not to send the organizer a decline (with notifyParticipants: true the server may send one).

  • Any other meeting (an organizer that is neither recognisably you nor someone who invited you, e.g. an alias the server does not report) is handled like one you organize: it is not changed or deleted without the opt-in flag, because the server may email the attendees.

Calendars for update and delete are chosen like for create: exact display name, URL or last URL segment, and only among MAILBOX_CALENDARS when that is set. A UID found in several calendars is refused until you name the calendar.

Read errors. When a calendar cannot be read, the read tools return an error naming it instead of an empty list or an all-free range (a partial list would show the unreadable calendar's meetings as free time). When the server cannot be reached, recently cached results are still served.

Sieve Filter Tools

Manage email filtering rules using the Sieve language (RFC 5228) through the ManageSieve protocol.

Tool

What it does

Hints

list_sieve_scripts

List the scripts on the server and which one is active

read-only

get_sieve_script

Return the source of one script

read-only

create_sieve_filter

Save a script under a name (replacing one of that name) after the server has checked it; activates it unless activate: false

destructive, idempotent

delete_sieve_script

Delete a script; the server refuses to delete the active one

destructive, idempotent

activate_sieve_script

Make one script the active filter; the previous one stays stored but stops running

destructive, idempotent

check_sieve_script

Check a script's syntax without saving it

read-only

get_sieve_capabilities

Show the server's limits and supported Sieve extensions

read-only

Example Use Cases

Automatic Newsletter Filtering:

require ["fileinto"];

if header :contains "From" [
  "newsletter@example.com",
  "news@company.com"
] {
  fileinto "Newsletter";
  stop;
}

Transaction Email Organization:

require ["fileinto"];

if anyof (
  header :contains "From" ["paypal.de", "stripe.com"],
  header :contains "Subject" ["Order", "Receipt", "Invoice"]
) {
  fileinto "Transactional";
  stop;
}

Ask Claude to manage your filters:

  • "Analyze my inbox and suggest email filters"

  • "Create a filter to move all GitHub notifications to a Developer folder"

  • "Show me all my active Sieve filters"

  • "Validate this Sieve script for syntax errors"

Prompts

Prompts are workflows you pick in the client (Claude Desktop lists them as attachable prompts or slash commands). They only write the opening request; the work is done by the tools above, which the client shows and asks you to approve as usual.

  • draft_reply (uid, optional folder): read one message with get_email and save a reply with create_draft, never sending it.

  • summarize_thread (messageId, optional folder): read a conversation with get_email_thread and summarise what was decided and what is still open.

Both remind the model that the mail is third-party content.

Resources

  • mailbox://folders (application/json): the folder list get_folders returns, with path, delimiter, flags and special-use role, for clients that let you attach reference data without a tool call.

Server Instructions

On connect the server sends short instructions that clients add to the model's context: folder names differ per account (call get_folders), UIDs are only valid in the folder they came from, and search_emails returns headers only.

Configuration

Environment Variables

Configuration is automatically validated at startup using comprehensive validation rules. The server will fail fast with clear error messages if any configuration is invalid or missing.

Required Configuration

  • MAILBOX_EMAIL: Your mailbox.org email address (required)

    • Must be a valid email address format

  • MAILBOX_PASSWORD: Your mailbox.org app password (required)

    • Must be a non-empty string

Optional Email Configuration

IMAP (Reading Emails):

  • MAILBOX_IMAP_HOST: IMAP server host (default: imap.mailbox.org)

    • Must be a non-empty string

  • MAILBOX_IMAP_PORT: IMAP server port (default: 993)

    • Must be a valid port number (1-65535)

  • MAILBOX_IMAP_SECURE: Use TLS encryption (default: true)

    • Must be "true" or "false"

SMTP (Sending Emails):

  • MAILBOX_SMTP_HOST: SMTP server host (default: smtp.mailbox.org)

    • Must be a non-empty string

    • IPv4/IPv6 (dual-stack) connection is handled by nodemailer: it resolves both address families and falls back to the other one when one is unreachable

  • MAILBOX_SMTP_PORT: SMTP server port (default: 465)

    • Must be a valid port number (1-65535)

  • MAILBOX_SMTP_SECURE: Use TLS encryption (default: true)

    • Must be "true" or "false"

    • Use true for port 465 (implicit TLS) and false for port 587 (STARTTLS)

    • TLS is always required: with false the connection must upgrade via STARTTLS, otherwise it is refused

    • The server certificate is verified, so MAILBOX_SMTP_HOST must be a hostname covered by the certificate (e.g. smtp.mailbox.org); an IP address fails verification

Optional Calendar Configuration

  • MAILBOX_CALDAV_URL: CalDAV server URL (default: https://dav.mailbox.org/)

    • Must be a valid URL format

  • MAILBOX_CALENDARS: Comma-separated list of calendars to access, for reading and writing. Entries match a calendar's exact display name, URL or last URL segment, never a substring; an entry that matches no calendar or several calendars is a configuration error, and the error lists the available calendars as Display Name (last URL segment). Events outside these calendars cannot be read, created, changed or deleted; the first entry is the default calendar for create_calendar_event

Breaking: MAILBOX_CALENDARS entries now match exactly (display name, URL, or last path segment); substring matches no longer work. An entry such as work that used to match .../work-calendar/ by substring is now refused with a configuration error listing the available calendars; use the display name or last URL segment shown there. This also applies to the calendar argument of the calendar tools.

Optional Sieve Configuration

  • MAILBOX_SIEVE_HOST: Sieve server host (default: imap.mailbox.org)

    • Must be a non-empty string

  • MAILBOX_SIEVE_PORT: Sieve server port (default: 4190)

    • Must be a valid port number (1-65535)

  • MAILBOX_SIEVE_SECURE: How the connection is encrypted (default: false)

    • Must be "true" or "false"

    • false: connect in plain text and upgrade with STARTTLS. STARTTLS is mandatory: the client refuses to authenticate if the server does not offer it or the upgrade fails. This is what the standard ManageSieve port 4190 (including mailbox.org) expects.

    • true: implicit TLS from the first byte. Only for servers that offer ManageSieve on a dedicated TLS port; the standard port 4190 does not speak implicit TLS.

    • In both modes the server certificate is always verified.

Optional Cache Configuration

Cache lifetimes are fixed in code: email searches and threads 5 min, single messages 10 min, the folder list 15 min, calendar events and calendar searches 15 min, free/busy 5 min. An entry read often may have its lifetime extended, up to one hour. When the server is unreachable, an expired cached copy is served for up to a day past its lifetime; with no cached copy the tool returns an error. Moving, flagging and deleting mail, saving drafts, creating folders and calendar changes clear the affected cached entries.

CACHE_EMAIL_SEARCH_TTL, CACHE_EMAIL_MESSAGE_TTL, CACHE_EMAIL_THREAD_TTL, CACHE_CALENDAR_EVENTS_TTL and CACHE_CALENDAR_FREEBUSY_TTL are still validated at startup (non-negative numbers) but have no effect.

  • CACHE_MAX_SIZE: Maximum cache entries (default: 1000)

    • Must be a positive integer

  • CACHE_CLEANUP_INTERVAL: Cache cleanup frequency in ms (default: 300000)

    • Must be at least 1000ms

Optional Connection Pool Configuration

Note: mailbox.org limits concurrent IMAP connections per account. Using more than 2-3 connections may cause connection issues.

  • POOL_MIN_CONNECTIONS: IMAP connections kept open while idle

    • Default: 1 in stdio mode, 0 in http mode

    • Must be between 0 and POOL_MAX_CONNECTIONS; a larger value is refused at startup

    • 0 means connect on demand. This is the default for hosted deployments: a host that stops the container when idle would otherwise see repeated background IMAP logins that are never used, which a mail provider may treat as suspicious activity

  • POOL_MAX_CONNECTIONS: Maximum IMAP connections (default: 3)

    • Must be between 1 and 100 connections

    • Also caps the SMTP pool, at most 5; without it the SMTP pool allows 2

  • POOL_TIMEOUT_MS: Connection acquire timeout (default: 15000)

    • Must be at least 1000ms

  • POOL_IDLE_TIMEOUT_MS: Idle connection timeout (default: 30000)

    • Must be at least 1000ms

  • POOL_HEALTH_CHECK_MS: Health check frequency (default: 6000)

    • Must be at least 1000ms

In stdio mode the IMAP pool keeps one connection open while idle (see POOL_MIN_CONNECTIONS). The SMTP pool connects on demand: checking an idle SMTP connection means a full login, so it is opened for a send and closed again once idle for POOL_IDLE_TIMEOUT_MS.

Optional Transport Configuration

  • MCP_TRANSPORT: stdio or http (default: stdio)

    • stdio is what Claude Desktop and Claude Code launch locally

    • http serves MCP over Streamable HTTP for hosted deployments (see Hosted Mode)

  • PORT: HTTP listen port (default: 8080, only used in http mode)

  • MCP_AUTH_TOKEN: Shared secret required by every HTTP request

    • Required in http mode; the server refuses to start without it

    • Must be at least 32 characters; generate with openssl rand -hex 32

  • PUBLIC_URL: Externally reachable origin, e.g. https://mcp.example.com

    • Optional. Setting it enables OAuth, which needs a stable public URL to publish in discovery metadata and to build redirects

    • Must be https, except localhost/127.0.0.1 for local testing

    • Origin only: a path, query or fragment is refused, since the OAuth endpoints are served at the root

    • Without it the server accepts only the static MCP_AUTH_TOKEN

  • OAUTH_ALLOWED_REDIRECT_HOSTS: Comma-separated hosts an OAuth client may register a redirect URI for

    • Defaults to claude.ai,claude.com

    • Loopback (localhost, 127.0.0.1, ::1) is always allowed on any port, since native clients such as Claude Code receive their callback locally

    • Hosts match exactly: allowing claude.ai does not allow sub.claude.ai or claude.ai.evil.example

Optional Debug Configuration

  • DEBUG: Enable debug logging (default: false)

    • Must be "true" or "false"

    • Tool calls are logged with the names and types of their arguments only, never their values, so mail content, recipients and Sieve scripts stay out of the log

Security Notes

  • Use app-specific passwords instead of your main password for better security

  • All credentials are passed via environment variables (no persistent storage)

  • Consider using a .env file for local development (add it to .gitignore)

  • In http mode, MCP_AUTH_TOKEN is the only thing between the network and your mailbox. Treat it like the mailbox password

  • Logs never contain credentials: only the authentication scheme of an Authorization header is recorded, a token placed in the URL path is redacted, and OAuth code and code_challenge values are excluded

Hosted Mode

The same server can run remotely over Streamable HTTP, which makes it usable from clients that cannot launch a local process. Run it on any container host with MCP_TRANSPORT=http.

Put TLS in front of it. The server speaks plain HTTP and binds to all interfaces (0.0.0.0) so a host's proxy can reach it. The bearer token and all mail content would cross the network in clear text without a TLS-terminating proxy or load balancer in front. Never expose the port directly to the internet.

Endpoints

  • POST /mcp: the MCP endpoint. Requires Authorization: Bearer <MCP_AUTH_TOKEN>. Stateless (no session IDs) with JSON responses, so nothing is lost when the host stops an idle container. GET is refused, so no long-lived SSE stream is held open. Bodies over 4 MiB are rejected

  • GET /health (or HEAD): unauthenticated liveness check, returns {"status":"ok"}. It does not touch mailbox.org

  • With PUBLIC_URL set: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /register, /authorize and /token (see How OAuth works here)

The token is accepted only in the Authorization header, never in the URL, where proxies and access logs would record it.

Run with Docker

docker build -t mailbox-mcp-server .
docker run --rm -p 127.0.0.1:8080:8080 \
  -e MAILBOX_EMAIL=you@mailbox.org \
  -e MAILBOX_PASSWORD='your-app-password' \
  -e MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  mailbox-mcp-server

The image defaults to MCP_TRANSPORT=http on port 8080 and runs as an unprivileged user. Pass credentials through your host's secret store rather than baking them into the image.

Connect a client

Claude Code sends the token as a header:

claude mcp add --transport http mailbox https://your-host.example/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Verify a deployment:

curl -s -o /dev/null -w "%{http_code}\n" https://your-host.example/mcp \
  -X POST -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

200 means the token was accepted; 401 means it was missing or did not match.

claude.ai (web and mobile) via OAuth. Custom connectors cannot send an Authorization header; the dialog only offers OAuth fields. Set PUBLIC_URL and add a custom connector pointing at the plain endpoint, with no credential in the URL:

https://your-host.example/mcp

Leave OAuth Client ID and OAuth Client Secret empty. The server supports dynamic client registration, so the client registers itself. PKCE is what ties an authorization code to the client that asked for it: a client registering as public gets no secret, and one registering as confidential is handed a secret that is never checked.

A browser page then names the application and the host the authorization code will be sent to. Check that destination before entering the value of MCP_AUTH_TOKEN. The client ends up holding a short-lived access token plus a refresh token, rather than a credential embedded in a URL.

Claude Desktop against the hosted server: bridge stdio to HTTP with a pinned mcp-remote version. It performs the OAuth flow itself and receives its callback on a loopback port, which the redirect allowlist permits:

{
  "mcpServers": {
    "mailbox": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.38", "https://your-host.example/mcp"]
    }
  }
}

Pin the version rather than using a floating mcp-remote, which would fetch the latest package on every launch and run it locally. This path is untested here; the local stdio setup is the usual way to use Claude Desktop with this server.

How OAuth works here

There is exactly one resource owner, so the authorization step is a form asking for MCP_AUTH_TOKEN rather than a user database. Everything else is carried in HMAC-signed tokens (authorization codes, access tokens, refresh tokens, even client registrations), so the flow needs no database and survives the container being restarted or stopped while idle.

Consequences worth knowing:

  • Revocation is all-or-nothing. Nothing is stored, so individual tokens cannot be revoked before they expire. Rotating MCP_AUTH_TOKEN changes the derived signing key and invalidates every outstanding token at once; that is the intended kill switch.

  • Access tokens last 1 hour, refresh tokens 30 days, authorization codes 60 seconds. Refreshing never extends a session past 30 days from the original authorization, and never widens the granted scopes, so the token has to be entered again at least monthly.

  • Rotating MCP_AUTH_TOKEN disconnects OAuth clients, since it is both the login credential and the signing key. Re-authorize the connector afterwards.

  • The static token keeps working as an Authorization: Bearer header on /mcp, so Claude Code is unaffected.

  • Registration is restricted. Anyone can reach /register, so a client may only register a redirect URI on an allowed host (see OAUTH_ALLOWED_REDIRECT_HOSTS). Without this, someone could register a client pointing at a host they control and send you an authorize link that looks entirely genuine. The consent screen also names the client and shows where the code will be sent, and refuses to be framed.

  • Rate limits apply per client address: 100 requests per 15 minutes on /authorize, 50 per 15 minutes on /token, 20 per hour on /register. The server trusts exactly one proxy hop for X-Forwarded-For, which matches a single TLS-terminating proxy in front of it.

Rotating the access token

MCP_AUTH_TOKEN is both the credential clients present and the secret the OAuth signing key is derived from, so rotating it is the kill switch for everything the server has issued: every OAuth access and refresh token, every client registration (the client_id is itself a signed token), and any client still using the old value as a bearer header.

Set a new MCP_AUTH_TOKEN on the host and restart the container, then update every client. claude.ai connectors must be removed and added again: they cannot be edited in place, and re-authorizing one with a stale client_id fails with invalid_client. Store the new value before you close the terminal: many hosts keep secrets write-only, so a lost token can only be replaced, not recovered.

Operational notes

  • Cold starts: if the host stops the container when idle, the first tool call re-establishes IMAP, CalDAV and Sieve connections and takes a few seconds. Pools connect on demand by default in http mode.

  • Logs: structured logs go to stderr. Rejected requests record the method, path, authentication scheme and which credential headers were present, never their values.

  • Do not point an external uptime monitor at /health if your host stops idle containers: it would keep the container awake.

Security Features

  • ✅ TLS encryption with certificate verification for IMAP, SMTP and CalDAV (with the default settings), and STARTTLS required for SMTP on port 587 and for ManageSieve

  • ✅ Connection pooling with health monitoring - automatic detection and recovery from failed connections

  • ✅ Environment-based credentials - no persistent storage of passwords

  • ✅ App-specific password support for enhanced security

  • ✅ Session-only caching - an in-memory cache, cleared on restart

  • ✅ No third-party data flow beyond your chosen client - mail content goes only between mailbox.org, this server, and the MCP client you connect

In stdio mode everything runs on your machine and nothing is exposed to the network. In http mode mail content passes through the host you deploy to, and the server adds:

  • ✅ Shared-secret authentication on every MCP request, compared in constant time over SHA-256 digests

  • ✅ Credential-free request logging - rejected requests are logged without the token they carried

  • ✅ OAuth 2.0 with PKCE, dynamic client registration, and short-lived tokens, so no credential need appear in a URL

  • ✅ Redirect URI allowlist - registration is open, so clients may only register a redirect on an allowed host (loopback excepted), preventing an authorization code being delivered to an attacker

  • ✅ Consent screen naming the requesting client and the destination of the authorization code

  • ✅ Stateless signed tokens, so no session store survives to be stolen, and rotating MCP_AUTH_TOKEN invalidates everything at once

Architecture

Connection Pooling

The server implements robust connection pooling for optimal performance and reliability:

SMTP Connection Pool

  • Verification Timing: Connections are verified based on configurable intervals to avoid unnecessary overhead

  • Failure Tracking: Monitors connection health and automatically destroys connections after repeated failures

  • Retry Logic: Automatic retry with exponential backoff for failed connection attempts

  • Metrics: Real-time monitoring of pool status, verification failures, and connection distribution

IMAP Connection Pool

  • Folder-Aware Pooling: Connections remember selected folders to minimize folder switching overhead

  • Health Monitoring: Periodic validation using IMAP NOOP commands

  • Connection Reuse: Intelligent reuse of connections for the same folder operations

  • State Management: Automatic cleanup of folder state for unhealthy connections

Base Pool Features

  • Sensible Defaults: Production-ready configuration that works out of the box

  • Simple Tuning: Five POOL_* environment variables cover the useful adjustments

  • Health Checks: Background monitoring and cleanup of idle/unhealthy connections

  • Graceful Shutdown: Proper cleanup of all connections on server termination

  • Error Recovery: Automatic recreation of failed connections with hardcoded retry logic

CalDAV and ManageSieve

  • CalDAV has no pool: requests go through a circuit breaker that stops calling the server for a while after repeated failures

  • ManageSieve opens a connection per tool call

Performance Benefits

  • Reduced Latency: Connection reuse eliminates costly connection establishment overhead

  • Better Throughput: Multiple concurrent operations through connection pooling

  • Resource Efficiency: Automatic scaling based on demand within configured limits

  • Reliability: Health monitoring ensures only working connections are used

Development

Setup

  1. Clone the repository:

    git clone https://github.com/soenkenils/mailbox-mcp-server.git
    cd mailbox-mcp-server
  2. Install dependencies:

    bun install

    Note: This project uses bun as the package manager and test runner. CI pins the bun version in .github/workflows/ci.yml.

  3. Create environment configuration:

    cp .env.example .env
    # Edit .env with your mailbox.org credentials

Debugging with the MCP Inspector

The MCP Inspector is a separate tool (not a dependency of this project) that launches the server over stdio and lets you list and call its tools, prompts and resources from a browser UI:

bun run build
npx @modelcontextprotocol/inspector node --env-file=.env dist/main.js

--env-file makes node load your .env, since the server does not read it itself. Add DEBUG=true to .env for debug-level logs, which go to stderr.

Available Scripts

  • bun run dev - Start the server from source with tsx watch, restarting on changes

  • bun run build - Compile src/ to dist/

  • bun run typecheck - Type-check src/ and tests/ (build covers src/ only)

  • bun run start - Start the built server (node dist/main.js)

  • bun run test - Run the test suite once

  • bun run test:watch - Run the tests in watch mode

  • bun run test:coverage - Run the tests with coverage and enforce the thresholds in vitest.config.ts

  • bun run test:e2e - Run the end-to-end check against a local IMAP server (see End-to-end checks)

  • bun run check - Lint and format check with Biome, read-only (what CI runs)

  • bun run fix - Apply what check can fix automatically

  • bun run format - Format code with Biome

  • bun run lint - Lint code with Biome

Testing

The tests live in tests/ and run with Vitest. They mock imapflow, nodemailer and tsdav, and the ManageSieve tests talk to a fake server on a local socket, so no test contacts mailbox.org; tests/integration.test.ts wires the real services together over those mocks. tests/toolContract.test.ts checks every tool's annotations, closed input schema and structured output.

# Run all tests
bun run test

# Run with coverage
bun run test:coverage

# Run one file, or tests matching a name
bun run test EmailService
bun run test -t "search"

CI (.github/workflows/ci.yml) runs, in order: bun install --frozen-lockfile, bun audit --audit-level=high (with documented ignores), bun run check, bun run build, bun run typecheck and bun run test:coverage. Run the same before pushing.

End-to-end checks

The unit tests mock imapflow entirely, so they cannot catch protocol-level regressions: a method that resolves false instead of throwing, a search criterion the server ignores, or a library upgrade that changes envelope shapes. tests/e2e/imap-e2e.mjs drives the built server over stdio against GreenMail, which keeps its mailboxes in memory and holds no real mail. The script refuses to run unless every host it hands the server (IMAP, SMTP, Sieve, CalDAV) is localhost or 127.0.0.1, and it does not pass on any MAILBOX_* variables from your shell, so your own mailbox is never touched.

The server only sends mail over TLS and always verifies the certificate, and GreenMail's built-in certificate is not issued for 127.0.0.1. So GreenMail is started with a throwaway test certificate, which the check then trusts:

# 1. A test certificate for 127.0.0.1 (valid 30 days)
mkdir -p /tmp/greenmail-tls && cd /tmp/greenmail-tls
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem \
  -days 30 -subj /CN=localhost -addext subjectAltName=IP:127.0.0.1,DNS:localhost
openssl pkcs12 -export -in cert.pem -inkey key.pem -out greenmail.p12 \
  -passout pass:changeit -name greenmail
cd -

# 2. Start a throwaway IMAP/SMTP server
docker run --rm -p 3143:3143 -p 3465:3465 -p 3993:3993 \
  -v /tmp/greenmail-tls:/certs:ro \
  -e GREENMAIL_OPTS='-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.users=e2e:e2epass@example.com -Dgreenmail.users.login=email -Dgreenmail.tls.keystore.file=/certs/greenmail.p12 -Dgreenmail.tls.keystore.password=changeit -Dgreenmail.tls.key.password=changeit' \
  greenmail/standalone:2.1.3

# 3. Build, then run the checks
bun run build
E2E_CA_FILE=/tmp/greenmail-tls/cert.pem bun run test:e2e

GreenMail cannot delete a folder a closed session had open, so the Trash folder the run creates outlives it; a second run against the same container skips the "no trash folder" case and says so. Restart the container to cover it again.

It covers folder creation (top-level and nested via parentPath) and cache invalidation, drafts, sending, searching (newest first, flag filters), fetching a message's addresses and body, flags, threading by Message-ID header, moving, permanent deletion (re-checked from a fresh process so a warm cache cannot mask it), and soft deletion with and without a trash folder. It exits non-zero if any check fails. It is not run in CI.

SMTP always goes over GreenMail's SMTPS port (3465). To run IMAP over TLS as well:

E2E_CA_FILE=/tmp/greenmail-tls/cert.pem E2E_IMAP_PORT=3993 E2E_IMAP_SECURE=true bun run test:e2e

Worth running before merging an upgrade to imapflow, mailparser, nodemailer or the MCP SDK. E2E_SERVER=/path/to/dist/main.js points the checks at another build, which is handy for comparing two revisions.

Dependencies

This project relies on the following key dependencies:

  • Runtime Dependencies

    • @modelcontextprotocol/server, @modelcontextprotocol/node, @modelcontextprotocol/core - MCP server implementation (SDK v2), its Node HTTP transport and shared types

    • imapflow - IMAP client for email access

    • nodemailer - SMTP client for sending mail

    • tsdav - CalDAV client for calendar access

    • ical.js - iCalendar parsing library

    • mailparser - Email message parsing

    • valibot - Validation of environment variables and tool arguments

    • dayjs - Date manipulation library

    • express, cors, express-rate-limit - OAuth endpoints in http mode (SDK v2 no longer ships them)

    ManageSieve is implemented directly on node:net/node:tls, without a library.

  • Development Dependencies

    • typescript - TypeScript compiler

    • vitest - Testing framework

    • @biomejs/biome - Code formatting and linting

    • tsx - Runs the TypeScript sources in bun run dev

    • @types/* - TypeScript type definitions

Troubleshooting

Common Issues

  1. Connection Issues

    • Verify your mailbox.org credentials in .env

    • Check if your account has IMAP and CalDAV access enabled

    • Ensure your network allows outbound connections to mailbox.org servers

    • SMTP certificate or TLS errors: use a hostname for MAILBOX_SMTP_HOST (not an IP address) and set MAILBOX_SMTP_SECURE=false when using port 587 (STARTTLS)

  2. Authentication Failures

    • Use an App Password instead of your main password

    • Make sure 2FA is properly configured if enabled

  3. Missing Dependencies

    # If you encounter module not found errors:
    bun install
  4. Debugging

Hosted mode

  1. The server exits at startup with MCP_AUTH_TOKEN

    • MCP_TRANSPORT=http needs a token of at least 32 characters.

  2. Every request returns 401

    • The token in the client does not match MCP_AUTH_TOKEN. If it is lost, rotate it.

    • The logs distinguish the cases: credentialHeaders: [] means nothing was sent, authScheme: Bearer means a credential arrived and did not match.

  3. A connector cannot complete OAuth

    • /register returning invalid_client_metadata means the redirect URI's host is not allowed; add it to OAUTH_ALLOWED_REDIRECT_HOSTS.

    • invalid_client on /authorize means the stored client_id is no longer valid, which happens after MCP_AUTH_TOKEN is rotated. Remove and re-add the connector.

    • OAuth endpoints returning 404 means PUBLIC_URL is not set.

  4. /mcp/<token> returns 404

    • Expected. Tokens are accepted only in the Authorization header.

  5. First call after idle is slow

    • Expected when the host stops idle containers: connections are re-established on demand.

Contributing

Contributions are welcome! Here's how you can help:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Please make sure to update tests as appropriate and follow the project's code style.

License

MIT License - see LICENSE file for details

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
      Enables Claude Desktop to securely access Amazon WorkMail email and calendar functionality through a local MCP server. Provides tools for reading, searching, and sending emails, as well as managing calendar events with built-in security protections.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to read, search, draft, send, flag, and move email across multiple IMAP/SMTP mailboxes while keeping credentials local.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Lets Claude Desktop read any IMAP mailbox and send emails via SMTP, with support for multiple mailboxes and locally stored credentials.
      13
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to read, search, send, and organize email over IMAP/SMTP and to manage calendars over CalDAV, including finding free slots and creating events, across multiple self-hosted accounts behind one authenticated endpoint.
      MIT