Mailoo MCP server

Mailoo

Mailoo is an open-source MCP server you run yourself to connect AI assistants and agents to multiple email accounts over IMAP and SMTP.

• Find what you need — search and read email, threads, and attachments across accounts.
• Act on email — prepare drafts, reply, and schedule messages through your assistant or agent.
• Choose your setup — guided setup for Claude Desktop or Cursor, or a standard MCP connection for your own agent.

Maintained by Bitfloo, forked from email-mcp. Licensed under LGPL-3.0-or-later; see NOTICE for attribution.

Quickstart for Claude Desktop or Cursor

Install Node.js 24 or newer and prepare your email account first, including an app password if your provider requires one. Then run these commands in a terminal:

npx -y @bitfloo/mailoo@latest account add
npx -y @bitfloo/mailoo@latest config edit
npx -y @bitfloo/mailoo@latest install

In config edit, press Enter to keep the rate limit (10 for a new config), then choose Yes for Read-only mode? (disables all write operations). This saves read-only mode in TOML. Choose your client in the installer, restart it, and ask: “Summarize up to five unread emails. Include each sender, subject and any requested next step. Ask which account to use if needed.”

The wizard prints a read-only/core manual client entry; the installer does not apply those environment overrides. This guided path uses the read-only setting you saved in TOML. With untouched default settings, the installer's entry runs writable/full.

Follow the guided setup and check your first result →

Quickstart for agent builders

With Node.js 24 or newer and account credentials ready, create a local account using npx -y @bitfloo/mailoo@latest account add. Connect your MCP client over stdio:

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"],
      "env": { "MCP_EMAIL_READ_ONLY": "true", "MCP_EMAIL_TOOLSET": "core" }
    }
  }
}

Initialize the connection, list tools, then call list_accounts, list_emails, and get_email with the returned account name and message ID.

Follow the MCP request sequence and inspect its results →

Both quickstarts configure read-only access for the first read. The walkthrough also covers feature requirements and fallbacks, including AI triage, local calendars, ManageSieve, and experimental OAuth.

To enable writes later, run config edit, keep the rate limit, and choose No for read-only mode; for the builder entry, set MCP_EMAIL_READ_ONLY to "false". Restart the server after either change. Request sending or changes explicitly when you intend them. You can request a dryRun: true preview separately; Mailoo does not require a preview before sending.

Mailoo connects to the mail servers you configure. Your MCP client and its model provider receive the mail content you request. Optional TypeSafe classification and webhooks send data to their configured services when enabled. Usage reporting is off by default. See Capabilities & data flows for destinations and fields.

Highlights

Up to 57 tools across full, core, and minimal profiles, up to 7 prompts, and 6 resources. Includes calendar and reminders, scheduling, ManageSieve filters, and optional AI triage. See API for tools and docs/tools.md for behaviour and limits.

Feature	In this tree
Multi-account IMAP/SMTP	✅
Send / reply / forward (with dryRun preview)	✅
Drafts & templates	✅
Provider-aware labels & bulk ops	✅
Schedule future emails	✅
Real-time IMAP IDLE watcher	✅
AI triage with presets	✅
Desktop & webhook alerts	✅
Calendar (ICS, Apple Calendar/Reminders)	✅
Email analytics	✅
OAuth2 (Gmail / M365)	✅ experimental
Guided setup wizard	✅
ManageSieve (server-side filters)	✅
Sender auth headers (SPF/DKIM/DMARC)	✅
Toolset profiles (full / core / minimal) & GBNF small-LLM ergonomics	✅
MCP outputSchema & structuredContent	✅

Table of Contents

• Highlights
• Quickstart for Claude Desktop or Cursor
• Quickstart for agent builders
• Security & Sandboxing Architecture
• LLM Ergonomics & Toolset Profiles
• Docs
• Background
• Install
• Usage
• Capabilities & data flows
• API
• Maintainers
• Contributing
• Attribution & License

Security & Sandboxing Architecture

Policy and how to report a vulnerability: SECURITY.md.

Mailoo applies controls to specific network, filesystem, and tool operations. It also labels untrusted mail for the model. Those labels do not guarantee how an LLM will respond to instructions inside an email.

Enforced operation controls:

• Zero Shell Execution (execFile only) — Native OS integrations (macOS osascript for Calendar/Reminders/notifications, Linux notify-send, Windows powershell, and crontab installation) invoke child_process.execFile with argument arrays (shell: false), avoiding shell parsing of arguments.
• SSRF & DNS-Rebinding Protection (net.BlockList) — Outbound alert webhooks validate URLs against an IPv4/IPv6 net.BlockList covering loopback, RFC 1918 private ranges, link-local/cloud metadata (169.254.169.254, 100.100.100.200), CGNAT, NAT64, 6to4, and reserved prefixes both at configuration time and at socket connection time (createWebhookConnectLookup), preventing DNS-rebinding attacks (src/safety/validation.ts).
• Symlink-Free Write Containment (savePath) — Attachment and .eml exports via savePath are strictly confined to the working directory, walk every path segment with lstat, refuse hidden dotfiles and OS persistence directories (Library/LaunchAgents, .ssh, .gnupg), and open targets with O_CREAT | O_EXCL | O_NOFOLLOW under a 50 MiB cap (5 MiB inline base64 cap). An .eml export is capped by its own size; an attachment by its encoded size in the message, which for base64 runs above the file size (details).
• Strict Credential File Permissions (0600) — config.toml is written and verified with mode 0600 inside a 0700 config directory ($XDG_CONFIG_HOME/mailoo/config.toml). Passwords and message bodies are redacted from the JSONL write audit log (src/safety/audit.ts).
• TLS & STARTTLS Verification — tls enforces implicit TLS with certificate verification (verify_ssl = true by default); starttls fails closed if the server does not advertise STARTTLS. Turning both off is accepted only for a loopback host. ManageSieve refuses AUTHENTICATE PLAIN over unencrypted sockets without STARTTLS.
• Operational Guardrails (MCP_EMAIL_READ_ONLY, MCP_EMAIL_TOOLSET, dryRun) —
  • MCP_EMAIL_READ_ONLY=true disables all write tools, background watchers, hooks, and schedulers at startup, exposing only the 31 read-only tools.
  • MCP_EMAIL_TOOLSET=full|core|minimal scopes the registered tool surface to match the agent's capability tier and context budget.
  • dryRun: true on high-risk tools (send_email, reply_email, forward_email, send_draft, delete_email, bulk_action, delete_mailbox, sieve_put_script, sieve_delete_script) validates all parameters and account resolution and returns a [DRY RUN] preview without modifying server state.
• Per-Account Rate Limiting — rate_limit (default 10 sends/minute) enforces an independent token bucket per account (src/safety/rate-limiter.ts). Buckets live in memory, so each server process and each mailoo scheduler check run counts on its own.

Untrusted-content labels: Email subjects, sender headers, bodies, previews, and authentication results are wrapped in <<<UNTRUSTED_EXTERNAL_CONTENT>>> … <<<END_UNTRUSTED_EXTERNAL_CONTENT>>> delimiters. Mailoo strips forged copies of these markers from the payload before wrapping it. This fencing identifies external content as data for the receiving model; it is not a sandbox for model behaviour or a guarantee against prompt injection.

LLM Ergonomics & Toolset Profiles

Mailoo is designed to work across both frontier models (Claude, GPT, Gemini) and local/small 3B–8B parameter models (llama.cpp GBNF grammars, Ollama, vLLM):

• Toolset Profiles (MCP_EMAIL_TOOLSET / settings.toolset):
  • full (default) — All 57 tools (31 in read_only mode), including Calendar, Reminders, ManageSieve, Watcher, Scheduler, Templates, Contacts, and Analytics.
  • core — 19 tools (10 in read_only mode) covering core email workflows (accounts, mailboxes, emails, threads, send, drafts, manage, bulk, attachments, health).
  • minimal — 14 tools (8 in read_only mode) tailored for 3B–4B models with tight context budgets (accounts, mailboxes, emails, send, manage, health).
• Optional account & Smart Account Resolution — When only a single account is configured or default_account (MCP_EMAIL_DEFAULT_ACCOUNT) is set, the account parameter is completely optional across tools. Account lookup also matches case-insensitively by profile name or email address (e.g., passing "you@example.com" resolves the matching account), and returns actionable error messages listing valid accounts (name (email) pairs) when ambiguous.
• Lossless Parameter Normalization & GBNF Compatibility — Single-message tools accept emailId, id, or email_id as either string or integer (42 or "42"). Batch tools (get_emails, bulk_action) accept string or numeric ID arrays (["42", "43"] or [42, 43]). list_emails and search_emails accept both hasAttachment and has_attachment. All Zod schemas avoid regex lookaheads so llama.cpp GBNF grammar compilation succeeds without errors.
• Context Window Protection — get_email and get_thread default to format="text" and enforce a default maxLength of 20000 characters (appending a clear truncation notice when exceeded) so large HTML newsletters never overflow small context windows.
• MCP outputSchema & structuredContent — Tools declare structured outputSchema contracts and return machine-readable structuredContent alongside human-readable text blocks.
• Outgoing attachment paths must be regular files under the working directory or home — Security considerations

Docs

Topic	Where
First account, Claude Desktop / Cursor, and an agent's first MCP calls	docs/getting-started.md
IMAP credentials, Gmail / iCloud app passwords, and experimental Google / Microsoft OAuth	docs/authentication.md
Sent APPEND, IMAP4rev2, Sieve, read_only, reconnect backoff, stdio EOF, shutdown, one mailbox writer per machine	docs/configuration.md
savePath, search dates, get_email_security, sieve tools, send/draft attachments, RFC 2047, protected folders, busy-mailbox timeout, bulk_action ids, calendar attachment saves	docs/tools.md
Performance notes	docs/performance-roadmap.md

Background

Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.

Key design decisions:

• XDG-compliant config — TOML at ~/.config/mailoo/config.toml
• Multi-account — Operate across multiple IMAP/SMTP accounts simultaneously
• Layered services — Business logic is decoupled from MCP wiring for testability
• Provider auto-detection — Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX

Install

Requires Node.js ≥ 24.

Before opening the wizard, prepare your provider credentials. For a complete first run, choose the Claude Desktop / Cursor or agent builder quickstart.

npx -y @bitfloo/mailoo@latest account add

That writes the local config and prints an MCP client snippet. The same package runs the server and the other commands:

npx -y @bitfloo/mailoo@latest
npx -y @bitfloo/mailoo@latest test

npx -y @bitfloo/mailoo@latest with no subcommand starts the MCP server over stdio. Keep the @latest tag: npx then checks the registry on every start, while a bare package name runs any copy installed globally or in the current project, however old. Or install the mailoo command:

npm install -g @bitfloo/mailoo
# or
pnpm add -g @bitfloo/mailoo
# or, without a global install:
pnpm dlx @bitfloo/mailoo account add

From a clone

Building this repository needs pnpm 12 (the packageManager version in package.json):

git clone https://github.com/Bitfloo/mailoo.git
cd mailoo
pnpm install && pnpm build
node dist/main.js account add

Docker

The running image needs Docker, not Node on the host. Create the config first with npx -y @bitfloo/mailoo@latest account add (or write the TOML by hand), then mount that directory into the container.

The image is ghcr.io/bitfloo/mailoo, built for linux/amd64 and linux/arm64. Version tags are bare semver (no v prefix); latest, alpine and the -bookworm / -alpine variants are published too. The 0.3 tag follows the newest 0.3.x release. Production setups should pin the full version from the release (it matches the npm version) or the image digest.

docker pull ghcr.io/bitfloo/mailoo:0.3

To build from a clone instead (docker-compose.yml uses build: .):

docker build -t ghcr.io/bitfloo/mailoo .

Note: The server uses stdio transport. Config is created on the host (npx -y @bitfloo/mailoo@latest account add, or a hand-written TOML) and mounted into the container.

Installing or starting Mailoo does not send a usage report. An install count stays off until MAILOO_INSTALL_COUNTER is 1, true, on, or yes (any letter case, surrounding spaces ignored) and MAILOO_INSTALL_COUNTER_URL is set. The POST body is only product, version, event (install), and node_major. Unset, 0, false, no, or off keeps it off. Full rules: Install count.

Usage

Commands below use npx -y @bitfloo/mailoo@latest. A global install accepts the same subcommands as mailoo. From a clone, after pnpm build, those subcommands are node dist/main.js (see From a clone).

Setup

# Add an email account interactively (recommended)
npx -y @bitfloo/mailoo@latest account add

# Or use the deprecated alias (same wizard)
npx -y @bitfloo/mailoo@latest setup

# Or create a template config manually
npx -y @bitfloo/mailoo@latest config init

The setup wizard auto-detects server settings, tests connections, saves config, and outputs the MCP client config snippet.

Test Connections

npx -y @bitfloo/mailoo@latest test            # all accounts
npx -y @bitfloo/mailoo@latest test personal   # specific account

npx -y @bitfloo/mailoo@latest test / mailoo test is a live-account connection probe, not Vitest. Unit and integration tests are pnpm test / pnpm test:integration (see Contributing). OAuth2 accounts log in with an access token refreshed from the configured refresh token.

Configure Your MCP Client

Run the guided installer for Claude Desktop, Cursor or Windsurf, or paste a snippet below for any client. Mailoo is published to the official MCP Registry as io.github.Bitfloo/mailoo.

npx -y @bitfloo/mailoo@latest install

The installer can register an npx, pnpm dlx, or global mailoo launch. A mailoo binary already on PATH can use "command": "mailoo" with "args": ["stdio"].

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
    }
  }
}

Register the server with the claude CLI. The default scope is the current project only. Put --scope user before the server name to make it available in every project, or --scope project to write a shareable .mcp.json; anything after the -- is passed to the server, not to claude:

claude mcp add mailoo -- npx -y @bitfloo/mailoo@latest stdio
# or, available in every project:
claude mcp add --scope user mailoo -- npx -y @bitfloo/mailoo@latest stdio

Mailoo is not in the VS Code Extensions gallery. Point Copilot at the npx launch below.

Workspace (.vscode/mcp.json):

{
  "servers": {
    "mailoo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
    }
  }
}

User config (settings.json, all workspaces):

Open the Command Palette → Preferences: Open User Settings (JSON) and add:

{
  "mcp": {
    "servers": {
      "mailoo": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
      }
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
    }
  }
}

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "mailoo": {
      "command": {
        "path": "npx",
        "args": ["-y", "@bitfloo/mailoo@latest", "stdio"]
      }
    }
  }
}

Add to ~/.vibe/config.toml:

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo@latest", "stdio"]

To pass credentials directly instead of using a config file, use the env field:

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo@latest", "stdio"]
env = { MCP_EMAIL_ADDRESS = "you@example.com", MCP_EMAIL_PASSWORD = "your-app-password", MCP_EMAIL_IMAP_HOST = "imap.example.com", MCP_EMAIL_SMTP_HOST = "smtp.example.com" }

MCP tools are exposed as mailoo_<tool_name> (e.g. mailoo_list_emails). Restart Vibe after editing the config.

Run the server in a container — mount your config directory read-only. The image is ghcr.io/bitfloo/mailoo:0.3 (or build it with docker build -t ghcr.io/bitfloo/mailoo .):

docker run --rm -i \
  -v ~/.config/mailoo:/home/node/.config/mailoo:ro \
  ghcr.io/bitfloo/mailoo:0.3

For MCP client configuration (e.g. Claude Desktop):

Replace /absolute/path/to/mailoo-config below with the full absolute path to the host directory containing config.toml. MCP clients spawn Docker directly: they do not expand ~ or shell variables in JSON arguments. The shell example above relies on shell expansion. On Windows with Docker Desktop, use a shared Windows host path such as C:/absolute/path/to/mailoo-config in this argument; do not copy the Unix path or shell line continuations.

{
  "mcpServers": {
    "mailoo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/mailoo-config:/home/node/.config/mailoo:ro",
        "ghcr.io/bitfloo/mailoo:0.3"
      ]
    }
  }
}

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo@latest", "stdio"],
      "env": {
        "MCP_EMAIL_ADDRESS": "you@example.com",
        "MCP_EMAIL_PASSWORD": "your-app-password",
        "MCP_EMAIL_IMAP_HOST": "imap.example.com",
        "MCP_EMAIL_SMTP_HOST": "smtp.example.com"
      }
    }
  }
}

CLI Commands

npx -y @bitfloo/mailoo@latest [command]

Commands:
  stdio                     Run as MCP server over stdio (default)
  http [port] [host]        Streamable HTTP (default: port 8080 on 127.0.0.1 and ::1)
  account list              List all configured accounts
  account add               Add a new email account interactively
  account edit [name]       Edit an existing account
  account delete [name]     Remove an account
  setup                     Deprecated alias for 'account add'
  test                      Test connections for all or a specific account
  install                   Register mailoo with MCP clients interactively
  install status            Show registration status for detected clients
  install remove            Unregister mailoo from MCP clients
  config show               Show config (passwords masked)
  config edit               Edit global settings (rate limit, read-only)
  config path               Print config file path
  config init               Create template config
  scheduler check           Process pending scheduled emails
  scheduler list            Show all scheduled emails
  scheduler install         Install OS-level scheduler (launchd/crontab)
  scheduler uninstall       Remove OS-level scheduler
  scheduler status          Show scheduler installation status
  notify test               Send a test desktop notification
  notify status             Check platform notification support
  --version, -v             Print the package version
  help                      Show help