Postale Email MCP

A read-only MCP server for Postale.io mailboxes. It syncs email over IMAP into a local SQLite mirror, then lets MCP clients browse and search the local copy by mailbox, date, date range, sender, recipient, subject, text, and thread.

What Is Fixed

This server is specific to Postale.io. You do not configure provider hostnames or ports.

• IMAP host: mail.postale.io
• IMAP port: 993
• TLS: enabled
• Username: your full email address

Requirements

• Node.js 20 or newer
• A Postale.io mailbox
• The mailbox email address and password

Setup

Install dependencies and build:

npm install
npm run build

Pass credentials as CLI args, or set them in the MCP client environment:

postale-email-mcp --email "[email protected]" --password "your mailbox password"

Environment fallback is still supported with POSTALE_EMAIL and POSTALE_PASSWORD.

Verify

Run the full local check before using or changing the server:

npm run verify

This runs unit tests, TypeScript checks, a production build, and an MCP stdio smoke check. The smoke check starts dist/index.js with dummy credentials and verifies that every expected MCP tool is registered. It does not connect to Postale.

Codex MCP Configuration

Use the npm package through npx:

{
  "mcpServers": {
    "postale-email": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "--email",
        "[email protected]",
        "--password",
        "your mailbox password"
      ]
    }
  }
}

Local Storage

The server stores the mirror under:

~/.postale-email-mcp/<account-hash>/
  emails.sqlite
  raw/

The account hash is derived from the email address. Passwords are not written to disk by this server.

Raw .eml files contain full email content. Treat the storage directory as sensitive data and protect it the same way you protect your mailbox.

Tools

• sync_email: sync all mailboxes, or one mailbox, into the local mirror.
• get_sync_status: show account, storage path, counts, latest message date, and last sync result.
• list_mailboxes: list known local mailboxes and message counts.
• browse_email_dates: bucket messages by day, week, or month.
• search_emails: full-text search local metadata and bodies with filters.
• list_emails: chronological filtered listing without full-text search.
• get_email: return full metadata and body for a single local email.
• get_thread: return locally known messages connected by Message-ID, In-Reply-To, and References.
• get_raw_email: return raw RFC822/MIME source for a local email, with a byte limit.
• get_storage_stats: show SQLite database, WAL, and page statistics.
• optimize_email_store: run lightweight SQLite and FTS maintenance.

List and search tools use limit, cursor, and nextCursor for keyset pagination.

First Live Check

After configuring real credentials in Codex, start with a small sync:

{
  "mailbox": "INBOX",
  "limit": 10
}

Call get_sync_status after the sync. If that looks right, run list_mailboxes, browse_email_dates, and a small search_emails query before syncing the whole mailbox.

Safety

The server is read-only. It does not send, delete, move, archive, mark read, or mutate flags. IMAP is used only to list and fetch messages for local sync.

IMAP mailboxes are opened read-only during sync. For local performance, the SQLite mirror uses WAL mode, a busy timeout, keyset pagination, and periodic SQLite/FTS optimization.

Development

npm test
npm run typecheck
npm run build
npm run smoke:mcp

Tests use fixtures and fake IMAP clients, so they do not require real Postale credentials.