Skip to content
MCP server

Mailoo - Email MCP Server

Run email for several accounts from an assistant, with read-only and dry-run guardrails

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.3.5
Listing updated
today

Similar MCP servers

About Mailoo - Email MCP Server

Mailoo - Email MCP Server is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

Mailoo is a self-hosted fork of email-mcp maintained by Bitfloo, and its notable trait is how cautious the defaults are. The quickstarts configure read-only mode first, which exposes only 31 read-only tools and turns off writes, watchers, hooks and schedulers, and toolset profiles (full, core, minimal) shrink the tool list for smaller context budgets. High-risk tools such as send_email accept a dryRun preview.

It connects to IMAP and SMTP accounts, with experimental OAuth2 for Gmail and Microsoft 365, and covers drafts and templates, scheduled sends, IMAP IDLE watching, labels and bulk operations, calendar and reminders, ManageSieve filters, SPF/DKIM/DMARC header checks, analytics and optional AI triage. In total the README counts up to 57 tools, 7 prompts and 6 resources.

Security notes cover execFile-only shell calls, SSRF protection on webhooks, symlink-safe attachment saving and 0600 config files. Mail content goes to your MCP client's model provider, and usage reporting is off by default.

Install

Run in a terminal

claude mcp add mailoo --env MCP_EMAIL_ADDRESS='<MCP_EMAIL_ADDRESS>' --env MCP_EMAIL_PASSWORD='<MCP_EMAIL_PASSWORD>' --env MCP_EMAIL_IMAP_HOST='<MCP_EMAIL_IMAP_HOST>' --env MCP_EMAIL_SMTP_HOST='<MCP_EMAIL_SMTP_HOST>' --env MCP_EMAIL_OAUTH2_CLIENT_SECRET='<MCP_EMAIL_OAUTH2_CLIENT_SECRET>' --env MCP_EMAIL_OAUTH2_REFRESH_TOKEN='<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>' --env MCP_EMAIL_ALERT_WEBHOOK_URL='<MCP_EMAIL_ALERT_WEBHOOK_URL>' --env MCP_EMAIL_HTTP_TOKEN='<MCP_EMAIL_HTTP_TOKEN>' -- npx -y @bitfloo/mailoo

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": [
        "-y",
        "@bitfloo/mailoo"
      ],
      "env": {
        "MCP_EMAIL_ADDRESS": "<MCP_EMAIL_ADDRESS>",
        "MCP_EMAIL_PASSWORD": "<MCP_EMAIL_PASSWORD>",
        "MCP_EMAIL_IMAP_HOST": "<MCP_EMAIL_IMAP_HOST>",
        "MCP_EMAIL_SMTP_HOST": "<MCP_EMAIL_SMTP_HOST>",
        "MCP_EMAIL_OAUTH2_CLIENT_SECRET": "<MCP_EMAIL_OAUTH2_CLIENT_SECRET>",
        "MCP_EMAIL_OAUTH2_REFRESH_TOKEN": "<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>",
        "MCP_EMAIL_ALERT_WEBHOOK_URL": "<MCP_EMAIL_ALERT_WEBHOOK_URL>",
        "MCP_EMAIL_HTTP_TOKEN": "<MCP_EMAIL_HTTP_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": [
        "-y",
        "@bitfloo/mailoo"
      ],
      "env": {
        "MCP_EMAIL_ADDRESS": "<MCP_EMAIL_ADDRESS>",
        "MCP_EMAIL_PASSWORD": "<MCP_EMAIL_PASSWORD>",
        "MCP_EMAIL_IMAP_HOST": "<MCP_EMAIL_IMAP_HOST>",
        "MCP_EMAIL_SMTP_HOST": "<MCP_EMAIL_SMTP_HOST>",
        "MCP_EMAIL_OAUTH2_CLIENT_SECRET": "<MCP_EMAIL_OAUTH2_CLIENT_SECRET>",
        "MCP_EMAIL_OAUTH2_REFRESH_TOKEN": "<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>",
        "MCP_EMAIL_ALERT_WEBHOOK_URL": "<MCP_EMAIL_ALERT_WEBHOOK_URL>",
        "MCP_EMAIL_HTTP_TOKEN": "<MCP_EMAIL_HTTP_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "mailoo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bitfloo/mailoo"
      ],
      "env": {
        "MCP_EMAIL_ADDRESS": "<MCP_EMAIL_ADDRESS>",
        "MCP_EMAIL_PASSWORD": "<MCP_EMAIL_PASSWORD>",
        "MCP_EMAIL_IMAP_HOST": "<MCP_EMAIL_IMAP_HOST>",
        "MCP_EMAIL_SMTP_HOST": "<MCP_EMAIL_SMTP_HOST>",
        "MCP_EMAIL_OAUTH2_CLIENT_SECRET": "<MCP_EMAIL_OAUTH2_CLIENT_SECRET>",
        "MCP_EMAIL_OAUTH2_REFRESH_TOKEN": "<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>",
        "MCP_EMAIL_ALERT_WEBHOOK_URL": "<MCP_EMAIL_ALERT_WEBHOOK_URL>",
        "MCP_EMAIL_HTTP_TOKEN": "<MCP_EMAIL_HTTP_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": [
        "-y",
        "@bitfloo/mailoo"
      ],
      "env": {
        "MCP_EMAIL_ADDRESS": "<MCP_EMAIL_ADDRESS>",
        "MCP_EMAIL_PASSWORD": "<MCP_EMAIL_PASSWORD>",
        "MCP_EMAIL_IMAP_HOST": "<MCP_EMAIL_IMAP_HOST>",
        "MCP_EMAIL_SMTP_HOST": "<MCP_EMAIL_SMTP_HOST>",
        "MCP_EMAIL_OAUTH2_CLIENT_SECRET": "<MCP_EMAIL_OAUTH2_CLIENT_SECRET>",
        "MCP_EMAIL_OAUTH2_REFRESH_TOKEN": "<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>",
        "MCP_EMAIL_ALERT_WEBHOOK_URL": "<MCP_EMAIL_ALERT_WEBHOOK_URL>",
        "MCP_EMAIL_HTTP_TOKEN": "<MCP_EMAIL_HTTP_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": [
        "-y",
        "@bitfloo/mailoo"
      ],
      "env": {
        "MCP_EMAIL_ADDRESS": "<MCP_EMAIL_ADDRESS>",
        "MCP_EMAIL_PASSWORD": "<MCP_EMAIL_PASSWORD>",
        "MCP_EMAIL_IMAP_HOST": "<MCP_EMAIL_IMAP_HOST>",
        "MCP_EMAIL_SMTP_HOST": "<MCP_EMAIL_SMTP_HOST>",
        "MCP_EMAIL_OAUTH2_CLIENT_SECRET": "<MCP_EMAIL_OAUTH2_CLIENT_SECRET>",
        "MCP_EMAIL_OAUTH2_REFRESH_TOKEN": "<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>",
        "MCP_EMAIL_ALERT_WEBHOOK_URL": "<MCP_EMAIL_ALERT_WEBHOOK_URL>",
        "MCP_EMAIL_HTTP_TOKEN": "<MCP_EMAIL_HTTP_TOKEN>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • MCP_EMAIL_ADDRESSEmail address. Required for the environment-variable account.Required
  • MCP_EMAIL_PASSWORDPassword or app password. Required unless MCP_EMAIL_OAUTH2_PROVIDER is set.
  • MCP_EMAIL_IMAP_HOSTIMAP server hostname.Required
  • MCP_EMAIL_SMTP_HOSTSMTP server hostname.Required
  • MCP_EMAIL_ACCOUNT_NAMEAccount name. Defaults to default.
  • MCP_EMAIL_FULL_NAMEDisplay name on sent mail.
  • MCP_EMAIL_USERNAMELogin username. Defaults to the email address.
  • MCP_EMAIL_IMAP_PORTIMAP port. Defaults to 993.
  • MCP_EMAIL_IMAP_TLSSet to false to turn off implicit IMAP TLS. Defaults to true.
  • MCP_EMAIL_IMAP_STARTTLSSet to true to upgrade IMAP with STARTTLS. Defaults to false.
  • MCP_EMAIL_IMAP_VERIFY_SSLSet to false to skip IMAP certificate verification. Defaults to true.
  • MCP_EMAIL_IMAP_DISABLE_IMAP4REV2Set to true to force IMAP4rev1 SEARCH.
  • MCP_EMAIL_SIEVE_HOSTManageSieve hostname. Defaults to the IMAP host.
  • MCP_EMAIL_SIEVE_PORTManageSieve port. Defaults to 4190.
  • MCP_EMAIL_SMTP_PORTSMTP port. Defaults to 465.
  • MCP_EMAIL_SMTP_TLSSet to false to turn off implicit SMTP TLS. Defaults to true.
  • MCP_EMAIL_SMTP_STARTTLSSet to true to upgrade SMTP with STARTTLS. Defaults to false.
  • MCP_EMAIL_SMTP_VERIFY_SSLSet to false to skip SMTP certificate verification. Defaults to true.
  • MCP_EMAIL_SMTP_POOL_ENABLEDSet to false to disable SMTP connection pooling. Defaults to true.
  • MCP_EMAIL_SMTP_POOL_MAX_CONNECTIONSMaximum pooled SMTP connections. Defaults to 1.
  • MCP_EMAIL_SMTP_POOL_MAX_MESSAGESMaximum messages per pooled SMTP connection. Defaults to 100.
  • MCP_EMAIL_OAUTH2_PROVIDEROAuth2 provider: google, microsoft, or custom. Configure custom in the config file: an account in the environment replaces the config file, so custom set here has no token_url or auth_url.
  • MCP_EMAIL_OAUTH2_CLIENT_IDOAuth2 client id.
  • MCP_EMAIL_OAUTH2_CLIENT_SECRETOAuth2 client secret.
  • MCP_EMAIL_OAUTH2_REFRESH_TOKENOAuth2 refresh token.
  • MCP_EMAIL_RATE_LIMITMaximum sends per minute. Defaults to 10.
  • MCP_EMAIL_READ_ONLYSet to true to omit write tools and mailbox writers.
  • MCP_EMAIL_SAVE_TO_SENTSet to false to skip the IMAP Sent copy after SMTP. Defaults to true.
  • MCP_EMAIL_WATCHER_ENABLEDSet to true to start the IMAP IDLE watcher.
  • MCP_EMAIL_WATCHER_FOLDERSComma-separated folders to watch. Defaults to INBOX.
  • MCP_EMAIL_WATCHER_IDLE_TIMEOUTIMAP IDLE timeout in seconds. Defaults to 1740.
  • MCP_EMAIL_HOOK_ON_NEW_EMAILWhat to do on arrival: triage, notify, or none.
  • MCP_EMAIL_HOOK_PRESETHook preset: inbox-zero, gtd, priority-focus, notification-only, or custom.
  • MCP_EMAIL_HOOK_AUTO_LABELSet to true to apply labels from hook triage.
  • MCP_EMAIL_HOOK_AUTO_FLAGSet to true to flag mail from hook triage.
  • MCP_EMAIL_HOOK_BATCH_DELAYSeconds to batch arrivals before hooks run. Defaults to 5.
  • MCP_EMAIL_HOOK_CUSTOM_INSTRUCTIONSExtra instructions appended to the hook preset.
  • MCP_EMAIL_ALERT_DESKTOPSet to true for desktop notifications.
  • MCP_EMAIL_ALERT_SOUNDSet to true to play a sound with desktop notifications.
  • MCP_EMAIL_ALERT_URGENCY_THRESHOLDMinimum urgency for an alert: urgent, high, normal, or low.
  • MCP_EMAIL_ALERT_WEBHOOK_URLHTTP or HTTPS URL that receives alert POSTs.
  • MCP_EMAIL_ALERT_WEBHOOK_ALLOW_PRIVATESet to true to allow webhook targets on a LAN, VPN, or tailnet.
  • MCP_EMAIL_HOOK_AUTO_CALENDARSet to true to create calendar events from hook triage.
  • MCP_EMAIL_HOOK_CALENDAR_NAMECalendar name for automatic events.
  • MCP_EMAIL_HOOK_CALENDAR_ALARM_MINUTESMinutes before an automatic event to alarm. Defaults to 15.
  • MCP_EMAIL_HOOK_CALENDAR_CONFIRMSet to false to skip confirming automatic calendar events. Defaults to true.
  • MCP_EMAIL_SYSTEM_ONE_ENABLEDSet to true to classify residue mail with System One. Off by default.
  • MCP_EMAIL_HTTP_HOSTHTTP listen address. Defaults to loopback. The host argument wins.
  • MCP_EMAIL_HTTP_TOKENBearer token. Required when the HTTP listen address is not loopback or MCP_EMAIL_HTTP_ALLOWED_HOSTS lists a non-loopback name.
  • MCP_EMAIL_HTTP_ALLOWED_HOSTSComma-separated Host names. Required for 0.0.0.0 and ::.
  • MCP_EMAIL_DEFAULT_ACCOUNTDefault account name or email address when the account parameter is omitted.
  • MCP_EMAIL_TOOLSETToolset profile to register: full, core, or minimal. Defaults to full.

Tools this server provides (4)

Taken from the project documentation; the running server may differ.

list_accounts
List configured email accounts
list_emails
List emails for an account
get_email
Fetch one email by account name and message ID
send_email
Send an email, with a dryRun preview option

What it does

Read-only mode
Disables write tools, watchers and schedulers at startup.
Toolset profiles
Full, core and minimal sets to fit an agent's context budget.
Multi-account IMAP/SMTP
Search and read mail, threads and attachments across accounts.
Dry-run sends
Preview high-risk actions such as sending before they happen.
Calendar and filters
ICS calendars, reminders and ManageSieve server-side filters.
AI triage
Optional classification with presets and alerts.

Good for

  • Summarise unread mail across several accounts
  • Draft and schedule replies with a preview before sending
  • Manage server-side Sieve filters from chat
  • Watch an inbox for important messages and raise desktop alerts

Pricing

Open source

LGPL-3.0-or-later; self-hosted

More servers for the same service

Mailoo - Email MCP Server FAQ

What do I need to run it?

Node.js 24 or newer and credentials for your mail account, including an app password if your provider requires one.

Can it be limited to reading?

Yes. Set read-only mode and the toolset to core or minimal.

What licence is it under?

LGPL-3.0-or-later.

Where does my mail go?

To the mail servers you configure and to your MCP client and its model provider when you ask for content.

Is Mailoo - Email MCP Server free?

Yes. Mailoo - Email MCP Server is open source, so you can use and self-host it for free.

How do I add Mailoo - Email MCP Server to Claude Code?

Run this command in your terminal: claude mcp add mailoo --env MCP_EMAIL_ADDRESS='<MCP_EMAIL_ADDRESS>' --env MCP_EMAIL_PASSWORD='<MCP_EMAIL_PASSWORD>' --env MCP_EMAIL_IMAP_HOST='<MCP_EMAIL_IMAP_HOST>' --env MCP_EMAIL_SMTP_HOST='<MCP_EMAIL_SMTP_HOST>' --env MCP_EMAIL_OAUTH2_CLIENT_SECRET='<MCP_EMAIL_OAUTH2_CLIENT_SECRET>' --env MCP_EMAIL_OAUTH2_REFRESH_TOKEN='<MCP_EMAIL_OAUTH2_REFRESH_TOKEN>' --env MCP_EMAIL_ALERT_WEBHOOK_URL='<MCP_EMAIL_ALERT_WEBHOOK_URL>' --env MCP_EMAIL_HTTP_TOKEN='<MCP_EMAIL_HTTP_TOKEN>' -- npx -y @bitfloo/mailoo

What are the best alternatives to Mailoo - Email MCP Server?

The closest alternatives to Mailoo - Email MCP Server are TrendRadar, Ha MCP, Concord MCP, Getmitra and note1.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers