How do I install Owlpost?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Owlpost need an API key?

The publisher lists these environment variables: OWLPOST_CONFIG.

What transport does Owlpost use?

Owlpost runs locally over stdio.

When was Owlpost last checked?

Last checked 2026-11-10. IMAP/SMTP email for iCloud, Gmail, Proton Bridge and more: search, read, follow threads, send.

Owlpost MCP server

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

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
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)

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 = "[email protected]"
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 = "[email protected]"
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:

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_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-<version>.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 [email protected]"
"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. 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.

Gmail

Requires 2FA and an app password.
IMAP must be enabled in Gmail settings → Forwarding and POP/IMAP.
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:

provider = "generic"
imap_host = "127.0.0.1", imap_port = 1143, imap_security = "starttls"
smtp_host = "127.0.0.1", smtp_port = 1025, smtp_security = "starttls"
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.

Found a vulnerability? See SECURITY.md.

Troubleshooting

Symptom	Fix
Tools don't show up in the client	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

See CONTRIBUTING.md for the release process and CHANGELOG.md for history.

License

MIT — see LICENSE.

Owlpost

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Owlpost?

Does Owlpost need an API key?

What transport does Owlpost use?

When was Owlpost last checked?

Documentation

owlpost

Contents

Features

Tools

Install

Configure

Where the config lives

Reference

Client setup

Claude Desktop

Claude Code

Cursor

VS Code

Other MCP clients

Docker

Examples

Provider notes

iCloud

Gmail

Proton Mail (via Proton Bridge)

Other providers

Security

Troubleshooting

Development

License