Mcp4mail

What mcp4mail MCP server does

The mcp4mail MCP server exposes connected IMAP mail accounts to an AI client through MCP. It can list accounts and folders, search messages by subject, sender, recipients, attachment name, and date, then retrieve message contents. Agents can also find addresses from previous correspondence and inspect connection details without receiving an account password.

Attachment retrieval supports either a short-lived download link or inline content for files up to 5 MB. The outgoing-status tool reports whether an email prepared through the send workflow has left the system.

Mailbox changes are available through separate tools. These include marking messages read or unread, applying flags, moving messages, creating folders, moving messages to Trash, and saving drafts. Sending is a two-step process: the tool prepares the message, and the email is sent only after the user approves it through the provided link.

How it works

The mcp4mail MCP server resolves every request through the signed-in user's own connected accounts. An account identifier belonging to another user is rejected before tool execution. Folders are opened with IMAP EXAMINE, so reading does not mark messages as seen.

The application keeps message headers—including sender, recipients, subject, date, flags, and size—in its database. That index is refreshed every 15 minutes, allowing searches without contacting the mail server for every query. Search results are limited to 50 per page, with additional per-user limits of 60 searches per 10 minutes and 1,000 returned rows per hour.

All mailbox tool calls are recorded in an audit table with the user, client, tool, account, outcome, result count, and duration. Arguments are not stored. Requests are also rate-limited to 120 per minute for each user and client pair, plus 240 tool calls per minute across a user's clients.

Setup and configuration

The mcp4mail MCP server is available at mcp4mail.online and can also be self-hosted. The documented self-hosting flow starts by copying .env.example to .env, filling in the values, and running docker compose up -d. The public HITCH_RESOURCE_URI must exactly match the service's public URL. The self-hosting guide also covers TLS and mailbox password storage.

For local development, bin/setup installs dependencies, prepares the database, and starts the development server. bin/dev runs the web server with the Tailwind watcher. PostgreSQL must be available locally, and bin/ci runs linting, security audits, tests, and system tests.

Mailbox connections use IMAP with a username and password. An app-specific password is recommended when the mail provider supports it. Production deployments should generate Active Record Encryption keys and provide them through encrypted credentials or the documented encryption environment variables. Mailbox passwords are encrypted at rest.

Tools and capabilities

The mcp4mail MCP server provides these tool groups:

• Account and folder discovery: list_mail_accounts, get_mail_account, and list_folders.
• Mail retrieval: search_messages, get_message, and get_attachment.
• Address lookup and delivery tracking: search_contacts and get_outgoing_status.
• Controlled mailbox changes: set_flags, move_message, trash_message, create_folder, and create_draft.
• Approval-gated mail preparation: send_message.

Limitations and notes

Every mailbox starts in read-only mode. An owner must enable “Allow the AI to make changes to this mailbox” and select the relevant permissions before write tools are accepted. Unticked operations are refused and logged as denied. The available permissions cover flags, moves and folders, drafts, sending or replying, and moving messages to Trash.

The server reads mailbox content whenever a connected AI client requests it, so only trusted clients should be connected. Inline attachments are limited to 5 MB, and send operations never bypass user approval. Gmail and other providers may require IMAP and app-password support to be enabled by the account holder or administrator.