Skip to main content
Glama
hugoheinzson

imap-2-mcp

by hugoheinzson
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

imap-2-mcp

MCP server that makes IMAP mailboxes searchable for AI clients such as Claude. It combines live IMAP access with a local SQLite FTS5 index that also covers attachment contents (PDF/DOCX/XLSX/text), so full-text search stays fast even for large mailboxes (50k+ messages).

Read-only against existing mail: it never sends, deletes, moves, or flags anything. The single write operation is create_draft, which APPENDs a new draft to the drafts folder — sending stays a manual step in your mail client (there is no SMTP in this project).

See SPEC.md for the full design and rationale.

Features (Phase 1)

  • Multi-account IMAP (SSL), read-only against existing mail.

  • Background sync worker: initial full index + periodic incremental updates.

  • Attachment text extraction (PDF, DOCX, XLSX, plain text).

  • Draft creation (create_draft): store a draft — optionally threaded as a reply — in the account's drafts folder; never sends.

  • MCP tools over streamable HTTP (client may run on another machine): list_mailboxes, list_recent, get_email, get_thread, search, search_attachments, get_attachment_text, create_draft, sync_status.

Related MCP server: Mailing Manager MCP

Quick start

cp .env.example .env      # fill in your IMAP account(s) — never commit this file
docker compose up --build

The server listens on :8000 (streamable HTTP). The first sync runs on startup; large mailboxes take a while to index initially.

To run a one-off index pass without serving:

docker compose run --rm imap-2-mcp python -m imap2mcp --sync-once

Configuration

All config is via environment variables (see .env.example). Declare accounts with ACCOUNTS=name1,name2 and one ACCOUNT_<NAME>_* block each (HOST, PORT, SSL, USER, PASSWORD). Secrets live only in your local .env, which is git-ignored.

Authentication

Set API_TOKEN in your .env to require a bearer token on every request. Clients then authenticate either via header or via a query parameter (useful for connector UIs that cannot set custom headers):

Authorization: Bearer <token>
# or
https://<host>/mcp?token=<token>

With API_TOKEN unset, the endpoint is unauthenticated — keep it on a trusted network only.

Connecting Claude

Add the streamable-HTTP endpoint as an MCP server, e.g. for Claude Code:

claude mcp add --transport http imap http://<home-server-ip>:8000/mcp

Security notes

  • Set API_TOKEN before exposing the server beyond your local network.

  • Without a token, only expose it inside your home network (LAN/VPN such as Tailscale). Do not port-forward it to the internet.

  • Phase 2 (public connector) will add full OAuth and a TLS tunnel.

Status

Phase 1 implementation. Not yet hardened or load-tested against a live mailbox.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-imap-server

    mattias242
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
    6
    -

  • IMAP Mail MCP

    FaisalFehad
    A
    license
    A
    quality
    D
    maintenance
    Enables LLM clients to read and search email via IMAP with tools for listing folders, searching messages, and fetching message content. It supports pagination, snippets, and thread context, and is designed for local AI workflows.
    10
    MIT

  • MailBridge MCP

    gexiro-global
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.
    Apache 2.0