IMAP Mail MCP

IMAP Mail MCP is an MCP (Model Context Protocol) server that lets LLM clients read email through IMAP tools.

It is designed for:

• local AI workflows (Cursor, ollmcp, other MCP hosts)

• mailbox exploration/search/summarization

• extension by developers who want to add mail tools

Current implementation is read-only (list/search/fetch/status/thread context/attachment metadata).

What You Get

• 10 MCP tools for common mail workflows

• consistent sorting and cursor pagination support

• guardrails for result size and snippet size

• deterministic tests plus CI

• TypeScript codebase that is easy to extend

Related MCP server: Email MCP Server

Quick Start

1. Install

git clone https://github.com/FaisalFehad/imap-mail-mcp.git
cd imap-mail-mcp
cp .env.example .env
npm install
npm run build

2. Configure .env

Set IMAP credentials in .env:

Proton Bridge users usually run with IMAP_HOST=127.0.0.1, IMAP_PORT=1143, IMAP_SECURE=false.

3. Run

node dist/index.js

Or via package bin:

npx imap-mail-mcp

Compatibility alias still works:

npx proton-bridge-mcp

MCP Client Setup

Cursor

Add server config (Settings -> MCP):

{
  "mcpServers": {
    "imap-mail": {
      "command": "node",
      "args": ["/absolute/path/to/imap-mail-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_USER": "your@proton.me",
        "IMAP_PASS": "your-bridge-password"
      }
    }
  }
}

ollmcp

1. Create ~/.config/ollmcp/mcp-servers/servers.json:

{
  "mcpServers": {
    "imap-mail": {
      "command": "node",
      "args": ["/absolute/path/to/imap-mail-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_USER": "your@proton.me",
        "IMAP_PASS": "your-bridge-password"
      },
      "disabled": false
    }
  }
}

2. Run:

ollmcp -j ~/.config/ollmcp/mcp-servers/servers.json

If ollmcp is not in PATH, use ~/.local/bin/ollmcp.

Tool Reference

Use mail_search_advanced as the default search entry point.

Common List/Search Options

Supported by list/search tools:

• limit: requested size (clamped by MAIL_MAX_RESULTS)

• sort: asc or desc (default desc)

• cursor: opaque cursor for next page

• includeSnippet: include snippet text in envelope results

• returnPage: return { items, nextCursor } instead of only array

Envelope result fields are stable:

{
  "uid": 123,
  "subject": "string",
  "from": "comma-separated addresses",
  "to": "comma-separated addresses",
  "date": "ISO-8601 string",
  "messageId": "optional string",
  "snippet": "optional string"
}

Example Workflows

Find unread billing mail in INBOX

1. mail_search_advanced with mailbox=INBOX, keyword=bill, unseen=true, limit=20

2. mail_get_message on the most relevant UID

Summarize a conversation before drafting a reply

1. mail_get_thread_context with target UID and limit

2. fetch one or two full messages with mail_get_message

3. summarize using context

Scan a large folder in pages

1. mail_list_messages with returnPage=true

2. pass returned nextCursor to next call until absent

Developer Guide (Use This Codebase)

Project Layout

src/index.ts   MCP server, tool schemas, handlers
src/imap.ts    IMAP operations and query behavior
src/query.ts   sorting/pagination/cursor/snippet helpers
src/config.ts  environment parsing and defaults
tests/*.test.mjs deterministic tests

Add a New Tool

1. Add schema in src/index.ts tool list.

2. Add handler branch in src/index.ts call handler.

3. Implement IMAP logic in src/imap.ts.

4. Add deterministic tests in tests/.

5. Update this README tool table.

Keep LLM Behavior Predictable

• keep envelope field names stable

• prefer additive changes (avoid breaking existing tool args)

• keep default ordering deterministic

• keep limits clamped

• avoid expensive full-mailbox scans where possible

Testing

Run deterministic tests (no live mailbox required):

npm test

Run live smoke test (requires real IMAP credentials):

node scripts/test-mcp.mjs

CI runs:

• npm ci

• npx tsc --noEmit

• npm test

Troubleshooting

Error: Command failed no such user (NO)

Usually bad IMAP_USER/IMAP_PASS or temporary server lockout after failed attempts.

Check:

• IMAP_USER is your IMAP login identity, not host/IP

• IMAP_PASS is correct for that IMAP account

• for Proton Bridge, use the Bridge-generated password

• wait a few minutes after repeated failed login attempts

TLS errors (wrong version number, ssl3_get_record)

You are likely using TLS against a plain IMAP port.

Fix:

• set IMAP_SECURE=false for local plain IMAP endpoints (common with Bridge)

• verify port matches secure/non-secure mode

Self-signed cert errors

If your IMAP endpoint uses self-signed certs:

• set IMAP_TLS_REJECT_UNAUTHORIZED=false

ollmcp: command not found

Install via pip/pipx/uvx, or run with full path:

~/.local/bin/ollmcp -j ~/.config/ollmcp/mcp-servers/servers.json

Security

• never commit .env or credential files

• keep IMAP credentials in MCP client env or local .env

• this implementation does not send or modify mail

License

MIT