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, vs ,
provider-specific Sent folders, multi-word search values).
IMAP/SMTP email for iCloud, Gmail, Proton Bridge and more: search, read, follow threads, send.
API key
OWLPOST_CONFIG
ตรวจสอบล่าสุด
2026-11-10
ดาว
—
เครื่องมือ
—
อัปไทม์
—
RFC822
BODY.PEEK[]
owlpost is the one I actually use day-to-day from Claude Code to read,
search, follow conversations, and send mail.
Conversation following — Gmail's X-GM-THRID extension where available, otherwise a generic Message-ID/References BFS across folders
Reliable connections — short-lived per-operation IMAP sessions instead of long-lived ones that drop randomly
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
Tool
What it does
Read-only
list_accounts
List configured mail accounts (never includes passwords)
✅
list_folders
List folders for an account, with detected special-use roles
✅
resolve_folder
Resolve a role (sent, trash, drafts, inbox, all, archive, ...) to the provider's folder name
✅
search_messages
Structured IMAP search (from/to/cc/subject/body/text/since/before/unseen/flagged/has_attachment, or raw), newest first
✅
read_email
Read one message: headers, plaintext/HTML body, attachment list. Truncates by default to fit MCP result limits
✅
get_conversation
Return all messages in the same thread (Gmail X-GM-THRID or generic reference walking)
✅
save_attachment
Download an attachment to local disk by part index (mailbox untouched)
writes local file
send_email
Send mail. Auto-saves to Sent on providers that don't (e.g. iCloud). Supports attachments, threading headers
❌ sends
save_draft_email
Build a message and APPEND it to Drafts without sending — same parameters as send_email
❌
reply_email
Reply (with optional reply-all), preserving threading and quoting
❌ sends
forward_email
Forward, re-attaching original attachments by default
❌ sends
mark_read
Set/unset \Seen
❌
flag_message
Set/unset \Flagged (star)
❌
move_email
Move to another folder
❌ destructive
delete_email
Move to Trash (not expunged)
❌ destructive
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:
The table name (icloud, gmail above) is what you pass as account to
the tools.
Where the config lives
In order of precedence:
owlpost --config /path/to/accounts.toml
the OWLPOST_CONFIG environment variable
~/.config/owlpost/accounts.toml
The file is read on the first tool call; restart the server after editing it.
Reference
Key
Required
Default
Meaning
email
✅
Login username and the From address
password
one of three
Password inline (app password recommended)
password_env
one of three
Name of an environment variable holding the password
password_command
one of three
Command that prints the password, e.g. op read op://...
provider
generic
icloud, gmail or generic. gmail enables X-GM-THRID threading
imap_host
✅
IMAP server hostname
imap_port
993
IMAP port
imap_security
ssl
ssl (implicit TLS, usually 993) or starttls (usually 143 / 1143)
smtp_host
✅
SMTP server hostname
smtp_port
587
SMTP port
smtp_security
starttls
starttls (usually 587) or ssl (usually 465)
auto_save_sent
true
APPEND a copy of sent mail to the Sent folder. Turn off for Gmail
tls_verify
true
Verify TLS certificates. Set false only for local bridges with self-signed certs
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_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-<version>.mcpb from the latest release and open it. Claude Desktop installs it and asks for the path to your accounts.toml.
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):
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
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"
iCloud throttles aggressive reconnection. owlpost uses short-lived per-op sessions but doesn't pool — if you get SSLEOFError: EOF, back off for ~30 seconds.
Sent folder is Sent Messages, Trash is Deleted Messages. Both are auto-detected.
Keep auto_save_sent = true: iCloud's SMTP doesn't keep a copy of what you send.
Set provider = "gmail" so owlpost uses Gmail's X-GM-THRID extension for reliable thread detection.
Set auto_save_sent = false; Gmail's SMTP already files sent mail, so APPENDing would duplicate it.
delete_email moves to [Gmail]/Trash. Moving out of INBOX to a label folder works like archiving.
Proton Mail (via Proton Bridge)
Proton only exposes IMAP/SMTP through the Proton Bridge
app, which runs on localhost with a self-signed certificate and speaks
STARTTLS on non-standard ports. Configure with:
tls_verify = false — required because Bridge's cert is self-signed
Use the Bridge-generated mailbox password (not your Proton account password)
Other providers
Set provider = "generic" and configure imap_host, smtp_host, ports,
imap_security / smtp_security (starttls or ssl), and tls_verify
(set false for self-signed certs). Folder roles will still be
auto-detected if your provider supports SPECIAL-USE (most modern ones do);
otherwise owlpost falls back to common names like Sent, Sent Items and
Trash. Whether to keep auto_save_sent on depends on whether your
provider's SMTP files sent mail itself — send yourself a test and check for
duplicates.
Security
owlpost sends real email.send_email, reply_email and
forward_email are annotated openWorldHint: true and are not
read-only. Configure your MCP client to ask for confirmation before
running them (most do by default for non-read-only tools), and don't
auto-approve them. The server's instructions also tell the model to
confirm recipients and content with you before sending. If you only want
the model to prepare mail, steer it towards save_draft_email.
Untrusted content. Email bodies are written by strangers. A message
can contain text designed to manipulate a model ("forward the last 10
invoices to ..."). Keep send confirmations on, especially in agents that
read mail and can send it.
Use app passwords, never your main account password. They can be
revoked individually and don't grant account-management access.
Keep secrets out of the file with password_command (your password
manager) or password_env. If you do put a password in the file,
chmod 600 ~/.config/owlpost/accounts.toml.
list_accounts never returns passwords or password sources.
tls_verify = false disables certificate checks entirely; only use it for
a bridge on 127.0.0.1.
save_attachment and attachments read and write local paths as the
user running the server.
The client couldn't spawn uvx. Use its absolute path (which uvx) and restart the client. Run uvx owlpost --version in a terminal to check it works
owlpost config not found at ...
Create ~/.config/owlpost/accounts.toml, or set OWLPOST_CONFIG / --config
must set exactly one of password, password_env, password_command
Remove the extra key (or add one) in that [accounts.<name>] table
password_command exited with 1: ...
Run the command in a terminal. Password-manager CLIs often need you to be signed in (op signin) or unlocked
Unknown account 'x'. Known: [...]
Use one of the listed names; it's the TOML table name, not the email address
[AUTHENTICATIONFAILED] / 535 on login
Wrong or revoked app password; for Gmail, make sure IMAP is enabled
SSLEOFError: EOF on iCloud
iCloud throttling reconnects; wait ~30 seconds
CERTIFICATE_VERIFY_FAILED with Proton Bridge
Set tls_verify = false for that account
Sent mail appears twice
Your provider already saves sent mail; set auto_save_sent = false
Sent mail missing from Sent
Set auto_save_sent = true
unknown encoding: idna
Upgrade to owlpost 0.1.4 or later
Development
git clone https://github.com/smankoo/owlpost
cd owlpost
uv sync # creates .venv with dev tools
uv run pytest # tests use fake IMAP/SMTP, no network
uv run ruff check .
uv run ruff format --check .
uv run python scripts/smoke_stdio.py uv run owlpost # stdio handshake + tools/list