imap-drafts-mcp

Leggi in italiano

An MCP server that lets Claude (or any MCP client) search and read an IMAP mailbox and prepare new messages as drafts only. It cannot send, move, delete or modify messages, and it does not mark them as read. A person reviews and sends every draft from their own mail client.

If you want no writing at all, set IMAP_READ_ONLY=true: see Read-only mode.

Developed by Creative Partnership Srl for internal use and released to everyone under the MIT license.

Why this server

An AI assistant that reads email also reads text written by strangers, and that text can try to give it instructions. This server limits what such an attack can achieve:

• There is no SMTP code and it takes no SMTP credentials, so it has no way to send.

• The only write command is IMAP APPEND, and its target is the Drafts folder. The folder is not a tool parameter, so the model cannot choose where to write.

• An automated test checks the commands that actually reach the IMAP server: nothing outside the allowed list, and every APPEND goes to Drafts.

Related MCP server: imap-mcp

Tools

Installation

You need uv and git. Add this to your MCP client configuration; for Claude Desktop that is claude_desktop_config.json:

{
  "mcpServers": {
    "mail": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/creativepartnership/imap-drafts-mcp@latest",
        "imap-drafts-mcp"
      ],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "name@example.com",
        "IMAP_PASSWORD": "<password>",
        "IMAP_FROM": "Your Name <name@example.com>"
      }
    }
  }
}

• @latest follows each new release: you get it the next time the client restarts, without changing anything.

• To update by hand instead, pin a version, for example @v0.2.0. With @latest, new code gets access to your mail without you reviewing it first, so pin a version if that matters to you.

• If the client cannot find uvx, use its absolute path as command (run which uvx to get it).

Read-only mode

Add "IMAP_READ_ONLY": "true" to env. The create_draft tool is then not registered, so the model does not see it and cannot be persuaded to use it, and the server writes nothing to the mailbox. A value other than true/false (1/0, yes/no, on/off also work) stops the server from starting, so a typo cannot leave drafts enabled.

Two limits to keep in mind:

• The guarantee covers this server, not the account. The password still gives full access to the mailbox, so protect it just the same.

• If you chose this mode for security, pin a version instead of using @latest. Otherwise you are also relying on every future release to keep the guarantee.

Configuration

Get the host and port from your mail provider. Port 993 with SSL/TLS is the most common setup; if your provider specifies 143 with STARTTLS, set IMAP_SECURITY=starttls and IMAP_PORT=143.

How the Drafts folder is found

1. IMAP_DRAFTS_FOLDER, if set. The folder must exist.

2. Otherwise, the folder the server marks with the SPECIAL-USE attribute \Drafts (RFC 6154).

If this does not give exactly one folder, create_draft returns an error asking you to set IMAP_DRAFTS_FOLDER. The name is never guessed. To check your server, call list_folders and look for \Drafts in the flags.

Provider notes

• Microsoft 365 / Outlook.com: not supported. Microsoft requires OAuth2 for IMAP, and this server only does password login.

• Gmail: requires an app password, which needs 2-Step Verification enabled.

Security

• No sending is possible. See Why this server.

• Drafts can only be added. Changing or deleting them would need STORE/EXPUNGE, which are not used. To correct a draft, create a new one and delete the old one by hand.

• Fixed sender, no header injection. From comes from the configuration. Subjects and addresses containing line breaks are rejected, and each to/cc entry must hold one valid address.

• No IMAP command injection. Search parameters reject control characters and are quoted.

• Prompt injection. An email can contain text that tries to instruct the AI. The server says so in its instructions and tool descriptions, but that is not a real defence. What remains possible is a draft prepared on the instructions of a malicious email, for example with confidential data addressed to a stranger. Whoever reviews a draft must check the recipients, not just the text. If the mailbox writes mostly to the same organisations, set IMAP_DRAFT_ALLOWED_DOMAINS.

• Credentials. The password sits in plain text in the client configuration. Use a dedicated or app-specific password where possible, protect the file (chmod 600 on Mac/Linux) and change the password if the file is shared.

• Data. The content of the emails you read passes through the AI service you use. For mailboxes holding other people's data, check that this is compatible with your policies and legal obligations.

To report a vulnerability, see SECURITY.md.

Known limitations

• Password login only (no OAuth2).

• Drafts are plain text, without attachments or Bcc.

• If the connection drops during a save, the server retries once, and in rare cases this can create a duplicate draft.

• text search runs on the IMAP server and does not look inside attachments. Use get_attachment_text on individual messages.

• Scanned PDFs (images only) return no text. Old .doc and .xls files are not supported.

• Threads are rebuilt by searching on the subject (without Re:/Fwd:) and linking messages through headers. A reply with a changed subject and no References can be missed.

• Searches with non-ASCII characters use CHARSET UTF-8, which very old IMAP servers may not support.

• stdio transport only (local use). Do not expose the server on a network without authentication.

Development

uv sync
uv run pytest

The tests run against a fake local IMAP server, so try a new version on a real mailbox as well before relying on it.

Releasing

1. Update the version in pyproject.toml, src/imap_drafts_mcp/__init__.py and CHANGELOG.md, then run uv lock.

2. Commit and push to main.

3. Run git tag vX.Y.Z && git push origin vX.Y.Z.

The Release workflow runs the tests and, if they pass, moves the latest tag to the new version. Everyone using @latest gets it at their next client restart, so try it on a real mailbox before step 3.

License

MIT