owlpost

owlpost

A high-fidelity IMAP/SMTP MCP server for iCloud, Gmail, and other mail providers. Built because every other email MCP server I tried got tripped up by real-world IMAP quirks (CRLF line endings, RFC822 vs BODY.PEEK[], provider-specific Sent folders, multi-word search values).

owlpost is the one I actually use day-to-day from Claude Code to read, search, follow conversations, and send mail.

uvx owlpost

Contents

• Features
• Tools
• Install
• Configure
• Client setup — Claude Desktop, Claude Code, Cursor, VS Code, Docker
• Provider notes — iCloud, Gmail, Proton Bridge, generic
• Security
• Troubleshooting
• Development

Features

• Multi-account — configure as many mailboxes as you want, switch by name
• iCloud and Gmail tested end-to-end, with provider-specific quirks handled:
• iCloud's RFC822 fetch returns empty bodies → uses BODY.PEEK[]
• iCloud's IMAP APPEND requires CRLF line endings → all outbound mail uses policy.SMTP
• iCloud's SMTP doesn't auto-save sent mail → owlpost APPENDs to Sent for you
• Gmail's SMTP *does* auto-save → owlpost skips the duplicate APPEND
• Folder names auto-discovered via RFC 6154 SPECIAL-USE (no hardcoding Sent Messages vs [Gmail]/Sent Mail)
• Servers without the MOVE extension get COPY + \Deleted + EXPUNGE instead
• Proton Bridge omits UID from FETCH responses unless asked → owlpost always asks
• Conversation following — Gmail's X-GM-THRID extension where available, otherwise a generic Message-ID/References BFS across folders
• Fast, reliable connections — logged-in IMAP sessions are reused for up to a minute (health-checked with NOOP, discarded after any error), every socket has a timeout, and read-only tools retry once if the server drops the connection
• Typed results — every tool publishes an MCP output schema and returns structured content
• MIME-aware — parses multipart messages, decodes headers, lists attachments, downloads them to disk
• Threaded reply/forward — preserves In-Reply-To/References, quotes the original
• Drafts — compose into the Drafts folder so you can review and send from your own mail client
• Read-only by default where it matters — searching and reading never mark mail as read
• Secrets stay out of the config file if you want — password_env and password_command (1Password, pass, Keychain, ...)
• Annotated tools — every tool declares MCP readOnlyHint / destructiveHint / openWorldHint, so clients can auto-approve reads and ask before sending

Tools

Every tool takes an account argument (the name from list_accounts). Messages are addressed by folder + uid, as returned by search_messages.

Install

The recommended way is to not install at all — let uvx fetch and cache it on first use. This keeps the package always up-to-date and avoids polluting your global Python environment:

uvx owlpost            # speaks MCP over stdio

uvx owlpost --version

If you'd rather have a stable binary on your PATH:

uv tool install owlpost   # or: pipx install owlpost / pip install owlpost

There's also a container image, see Docker.

Configure

Copy accounts.example.toml to ~/.config/owlpost/accounts.toml and fill in your credentials. Use app-specific passwords, not your real password:

• iCloud: account.apple.com → Sign-In and Security → App-Specific Passwords
• Gmail: myaccount.google.com/apppasswords (2FA must be enabled)

[accounts.icloud]

email = "you@icloud.com" password_command = "op read op://Private/iCloud Mail/app-password" provider = "icloud" imap_host = "imap.mail.me.com" smtp_host = "smtp.mail.me.com" auto_save_sent = true # iCloud SMTP doesn't auto-save sent

[accounts.gmail] email = "you@gmail.com" password_env = "OWLPOST_GMAIL_PASSWORD" provider = "gmail" imap_host = "imap.gmail.com" smtp_host = "smtp.gmail.com" auto_save_sent = false # Gmail SMTP auto-saves

The table name (icloud, gmail above) is what you pass as account to the tools.

Where the config lives

In order of precedence:

1. owlpost --config /path/to/accounts.toml
2. the OWLPOST_CONFIG environment variable
3. ~/.config/owlpost/accounts.toml

The file is read on the first tool call; restart the server after editing it.

Reference

Exactly one of password, password_env and password_command must be set.

`password_command` is split with shell-like quoting rules and run directly (no shell, so no pipes or $VARS), with a 10 second timeout. Its stdout, minus the trailing newline, is the password. It runs the first time the account is used and the result is cached for the life of the server process. If it fails, the tool call returns an error with the command's exit code and stderr. Some examples:

password_command = "op read op://Private/Fastmail/app-password"                  # 1Password CLI

password_command = "pass show mail/fastmail" # pass password_command = "security find-generic-password -s owlpost-icloud -w" # macOS Keychain password_command = "secret-tool lookup service owlpost account icloud" # GNOME Keyring

`password_env` reads the variable from the server's environment, which your MCP client controls (the env block in the snippets below).

Client setup

All of these run uvx owlpost. If your client can't find uvx, use the absolute path (typically ~/.local/bin/uvx, see which uvx). If you installed with uv tool install, you can use owlpost as the command instead.

Claude Desktop

One-click: download owlpost- .mcpb from the latest release and open it. Claude Desktop installs it and asks for the path to your accounts.toml.

Manual:

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{

"mcpServers": { "owlpost": { "command": "uvx", "args": ["owlpost"] } } }

Claude Code

claude mcp add owlpost --scope user -- uvx owlpost

with a non-default config path, or a password from the environment

claude mcp add owlpost --scope user \ -e OWLPOST_CONFIG=/path/to/accounts.toml \ -- uvx owlpost

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{

"mcpServers": { "owlpost": { "command": "uvx", "args": ["owlpost"] } } }

VS Code

Add to .vscode/mcp.json in your workspace (or run MCP: Add Server for a user-level install):

{

"servers": { "owlpost": { "type": "stdio", "command": "uvx", "args": ["owlpost"] } } }

Other MCP clients

owlpost speaks the standard MCP stdio transport — any MCP-compatible client can talk to it by spawning uvx owlpost or the installed owlpost binary. Pass env: {"OWLPOST_CONFIG": "..."} to point it at a config file.

Docker

The image expects the config at /config/accounts.toml. Mount the directory that contains it, read-only:

docker run -i --rm \

--mount type=bind,src="$HOME/.config/owlpost",dst=/config,readonly \ ghcr.io/smankoo/owlpost:latest

As an MCP client entry:

{

"mcpServers": { "owlpost": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/home/you/.config/owlpost,dst=/config,readonly", "ghcr.io/smankoo/owlpost:latest" ] } } }

Inside the container password_command can only run binaries that exist in the image, so use password or password_env (pass it with -e OWLPOST_GMAIL_PASSWORD). To reach Proton Bridge on the host, use --network host (Linux) or imap_host = "host.docker.internal". save_attachment writes inside the container unless you mount a writable directory for it.

Examples

Once registered, you can ask things like:

• *"Find emails from the school about the field trip in the last month"*
• *"Show me the full thread for the latest mortgage email"*
• *"Reply to the most recent message from the landlord saying I'll be in touch tomorrow"*
• *"Draft a reply to the insurance renewal asking for the PDF, don't send it"*
• *"Forward the policy PDFs to you@example.com"*
• *"Save the attachment from this month's electricity bill to ~/Downloads"*

Provider notes

iCloud

• Use an app-specific password, not your Apple ID password.
• iCloud throttles aggressive reconnection.