Mailoo

Mailoo is Bitfloo's IMAP, SMTP, and ManageSieve MCP server: multi-mailbox, with profiles per account and per folder.

This is a public LGPL-3.0-or-later fork of email-mcp. It is not an official codefuturist project. See Upstream / Attribution.

Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 56 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support (experimental), email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, customizable presets and static rules, ManageSieve filters, and a guided setup wizard.

Behaviour for Sent copies, IMAP4rev2, Sieve, attachment savePath, and read-only side effects is documented in docs/configuration.md and docs/tools.md.

Highlights

Table of Contents

• Highlights
• Security
• Docs
• Background
• Install
• Usage
• Capabilities & data flows
• API
• Maintainers
• Upstream / Attribution
• Contributing
• License

Security

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

• tls is implicit TLS; starttls fails the connection when the server offers no STARTTLS. With both false, IMAP and SMTP differ — see Security considerations.
• The audit log redacts passwords and message bodies. It records send, draft, folder, label, bulk, manage, sieve, template, and schedule writes, not every local write (src/safety/audit.ts) — SECURITY.md
• One global rate_limit (default 10 per minute) sizes a separate send bucket for each account (src/config/schema.ts)
• OAuth2 XOAUTH2 authentication for Gmail and Microsoft 365 (experimental)
• savePath writes a new file only under a specific working directory — Security considerations
• Outgoing attachment paths must be regular files under the working directory or home — Security considerations

Docs

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.

npx -y @bitfloo/mailoo setup

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
npx -y @bitfloo/mailoo account add
npx -y @bitfloo/mailoo test

npx -y @bitfloo/mailoo with no subcommand starts the MCP server over stdio. 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 setup

From a clone

Building this repository needs pnpm 9:

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

Docker

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

The image is ghcr.io/bitfloo/mailoo. Tags are bare semver (no v prefix), for example ghcr.io/bitfloo/mailoo:0.1.5. Anonymous pull is not available, so build locally (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 setup, or a hand-written TOML) and mounted into the container.

Usage

Commands below use npx -y @bitfloo/mailoo. 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 account add

# Or use the legacy alias
npx -y @bitfloo/mailoo setup

# Or create a template config manually
npx -y @bitfloo/mailoo 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 test            # all accounts
npx -y @bitfloo/mailoo test personal   # specific account

npx -y @bitfloo/mailoo test / mailoo test is a live-account connection probe, not Vitest. Unit and integration tests are pnpm test / pnpm test:integration (see Contributing).

Configure Your MCP Client

Run the guided installer, or paste a snippet below. There is no VS Code / MCP gallery listing.

npx -y @bitfloo/mailoo 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"].

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

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

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

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

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

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

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

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo", "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" }

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