better-email-mcp

An MCP server that gives LLM tools access to your email, calendar, tasks, and contacts — built to be the one you actually want to use.

Why "better"?

• Virtually zero dependencies. The only runtime dependency is the MCP SDK itself. IMAP, SMTP, CalDAV, and CardDAV clients are implemented from scratch using Node built-ins — no third-party libraries in your supply chain.
• Works with any provider. Supports IMAP/SMTP (Gmail, Outlook, self-hosted, etc.), Fastmail JMAP (email + contacts), and any CalDAV/CardDAV server (Fastmail, iCloud, Nextcloud, Radicale, etc.) for calendars, tasks, and contacts.
• You control what the LLM can do. Disable any tool with a single environment variable — enforce read-only access, hide search, or strip it down to just what you need. Less tool clutter means better LLM performance.
• Token-efficient. List and search responses return only essential fields by default. Pass verbose: true for full details when needed.

Token efficiency

All tool responses use compact JSON (no pretty-printing). List and search tools (list_messages, search_messages, list_events, search_events, list_tasks, search_tasks, list_contacts, search_contacts) return a lean field set by default — just enough to identify and triage each item. Pass verbose: true to get the full response with all fields.

Tool definition token cost (schema tokens consumed per request, estimated at ~3.5 chars/token):

Tools are only registered when the matching backend is configured. Combine rows to estimate your setup:

Example totals: IMAP only ~373 · IMAP + CalDAV + Tasks ~935 · Full suite (JMAP + CalDAV + Tasks + CardDAV) ~1,148

Run npm run count-tokens for a per-tool breakdown. Use DISABLED_TOOLS to trim tools you don't need.

Default fields by tool type:

The folder, calendar, and addressBook fields are automatically included in lean responses when no filter is applied (listing across all), and omitted when filtering by a specific one (since it's redundant).

Setup

Install and run directly with npx — no clone needed:

npx better-email-mcp

Or install globally:

npm install -g better-email-mcp

For local development:

git clone https://github.com/samteezy/better-email-mcp.git
cd better-email-mcp
npm install
npm run build

Configuration

The server is configured entirely through environment variables.

Backend selection

When set to html, the send_message tool requires an htmlBody field in addition to textBody, and messages are sent as multipart with both plain text and HTML. When set to plain (the default), only textBody is exposed — the LLM cannot generate HTML email.

JMAP (Fastmail)

To get a token, go to Fastmail Settings > Privacy & Security > API tokens and create a token with the email scopes you need.

IMAP

SMTP (sending from IMAP)

To enable sending with the IMAP backend, configure an SMTP server:

If SMTP_HOST is not set, the IMAP backend is read-only and the send_message tool is not registered.

CalDAV (calendar)

Calendar and task tools activate when CALDAV_URL is set. Works alongside any email backend. Tasks use CalDAV VTODO — supported by Fastmail, iCloud, Nextcloud, Radicale, and most CalDAV servers.

Contacts

When using the JMAP backend, contact tools activate automatically via JMAP Contacts (RFC 9610) — no extra configuration needed. To use CardDAV instead (or with the IMAP backend), set CARDDAV_URL:

CardDAV (optional override)

Disabling tools

Set DISABLED_TOOLS to a comma-separated list of tool names to prevent them from being registered:

DISABLED_TOOLS=send_message,search_messages

This is useful for enforcing read-only access or reducing context for the LLM. When using CALDAV_DEFAULT_CALENDAR or CARDDAV_DEFAULT_ADDRESS_BOOK, you can also disable list_calendars or list_address_books since the LLM no longer needs to discover them.

Attachment downloads

The get_attachment tool supports a saveTo parameter that writes the file to disk instead of returning base64 content. For security, saveTo paths are restricted to a base directory:

ATTACHMENT_DIR=~/Downloads  # default; set to change the allowed directory

Usage with MCP clients

JMAP (Fastmail) — email + contacts

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["better-email-mcp"],
      "env": {
        "EMAIL_BACKEND": "jmap",
        "JMAP_TOKEN": "your-fastmail-api-token"
      }
    }
  }
}

Contact tools are included automatically via JMAP — no CardDAV setup needed.

IMAP

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["better-email-mcp"],
      "env": {
        "EMAIL_BACKEND": "imap",
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "you@example.com",
        "IMAP_PASSWORD": "your-password",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_USER": "you@example.com",
        "SMTP_PASSWORD": "your-password"
      }
    }
  }
}

JMAP + CalDAV (Fastmail, all features)

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["better-email-mcp"],
      "env": {
        "EMAIL_BACKEND": "jmap",
        "JMAP_TOKEN": "your-fastmail-api-token",
        "CALDAV_URL": "https://caldav.fastmail.com/",
        "CALDAV_USERNAME": "you@fastmail.com",
        "CALDAV_PASSWORD": "your-app-password"
      }
    }
  }
}

Email and contacts use JMAP (automatic), calendar uses CalDAV. To use CardDAV for contacts instead, set CARDDAV_URL (this overrides JMAP contacts).

Tools

Email

Calendar (CalDAV)

Tasks (CalDAV VTODO)

Contacts (CardDAV)