NAME
mcp-imap - inspect and manage one IMAP account through MCP
SYNOPSIS
mcp-imap [OPTION]...
mcp-imap [OPTION]... login [method password|oauth2] [server HOST]
[user USER] [tls ssl|starttls] [port PORT] [oauth-KEY VALUE]...
mcp-imap [OPTION]... providers [SEARCH]
DESCRIPTION
Each --name selects one IMAP account and an independent MCP permission profile. Configure the account with login, then run the MCP server with --stdio, --connect, or an HTTP listener. Login takes passwords from the controlling terminal without echo, never from command-line arguments or MCP tools.
The account is stored as imap-NAME.ini under $XDG_CONFIG_HOME/anyevent-mcp or ~/.config/anyevent-mcp, mode 0600. Password data is Base64 in that private file, not encrypted. Protect the file like a password. Repeating login replaces the saved password after a successful connection. For login method oauth2, it prints a browser authorization URL and accepts the resulting redirect URL from the terminal, without listening on a callback port. The private file stores the refresh token; later IMAP sessions refresh access tokens automatically. Neither passwords nor OAuth tokens are accepted as command-line values. Unencrypted IMAP authentication is not supported.
providers searches Thunderbird's ISPDB domain index and OAuth provider definitions. With no argument it lists known domains. A domain, substring, or full email address selects a provider and looks up provider-hosted HTTPS autoconfig (preferred) or Thunderbird's ISPDB as a fallback. It prints shell-quoted password login commands for supported IMAP/TLS alternatives, provider setup instructions, and OAuth commands if a matching public OAuth registration is known. An email address fills in the username. The commands are NOT executed. Thunderbird's client registrations may not be usable by unrelated applications. OAuth authorization requests need registered redirect URIs and may require provider-specific optional oauth-auth-NAME VALUE arguments (e.g. oauth-auth-access_type offline).
OAuth2 login accepts oauth-client-id, optional oauth-client-secret, oauth-authorization-endpoint, oauth-token-endpoint, oauth-scope, and oauth-redirect-uri. Optional oauth-client-auth selects none, client_secret_post (default when a secret is supplied) or client_secret_basic. oauth-pkce defaults to 1 (S256), or 0 when a provider registration does not support PKCE. oauth-sasl selects xoauth2 (default) or oauthbearer, depending on the IMAP server. Additional authorization query parameters use oauth-auth-NAME VALUE. Successful OAuth2 login requires a refresh token; provider-specific offline access parameters may be necessary. Authorization is human-initiated only, never exposed through an MCP tool. After authorization, the browser will normally show an error page because no server is listening on the loopback redirect URI. This is expected; copy the full redirect URL from the address bar anyway. Port 1 works with Chromium's error-page behavior, but provider redirect registrations and other browsers may differ.
IMAP runs in a separate persistent synchronous worker, so an IMAP command does not block the MCP event loop. One request at a time is processed by the worker. A dropped connection during a write can leave an unknown outcome; do not blindly retry such writes.
Message references consist of mailbox, UIDVALIDITY and UID. Read operations use BODY.PEEK, never mark messages Seen. Deleted flags do not automatically expunge. EXPUNGE is explicit. Selecting another mailbox or logging out does not expunge. Search is bounded by UID windows, potentially returning a partial/empty page with a continuation cursor when matches are sparse.
FIRST USE
Discover your provider's settings before logging in:
mcp-imap --name personal providers alice@example.net
Replace the example address. This reports possible IMAP settings and login commands; provider-specific OAuth client registrations may be restricted to their original application. For a password-based provider, for example:
mcp-imap --name personal login method password \
server imap.example.net user alice@example.net tls ssl port 993
The password is read interactively. For OAuth2, run login method oauth2 with your provider-approved client ID, authorization/token endpoints, scope and redirect URI. For example, the structure of such a command (the provider URLs and registration below are placeholders) is:
mcp-imap --name personal login method oauth2 \
server imap.example.net user alice@example.net tls ssl port 993 \
oauth-client-id REGISTERED_CLIENT_ID \
oauth-authorization-endpoint https://login.example.net/authorize \
oauth-token-endpoint https://login.example.net/token \
oauth-scope MAIL_SCOPE \
oauth-redirect-uri http://127.0.0.1:1
The redirect URI must be allowed by the OAuth client registration. Some providers additionally require oauth-auth-access_type offline or other authorization parameters to issue a refresh token. After opening the printed authorization URL, authorize the intended account and paste the full redirect URL from the browser's address bar even if the browser reports an unreachable loopback page. Login checks IMAP authentication before saving the account.
Then configure your MCP client to start:
mcp-imap --name personal --stdio
Or expose it through a multibroker:
mcp-multibroker --stdio mail --- mcp-imap --name personal --stdio ---
Ask the assistant:
List my subscribed mailboxes, then show the ten newest subjects
and senders in INBOX. Do not modify flags or move messages.
For example, to subscribe a folder called Receipts, invoke mailbox with {"operation":"subscribe","mailbox":"Receipts"}, then call lsub to see subscribed folders. Read operations request read permission; changing subscriptions requires manage. A mailbox-specific permission prompt can allow just that mailbox or all mailboxes.
To let a separately started server join an existing multibroker with an HTTP/extension listener, run:
mcp-imap --name personal --connect http://127.0.0.1:31740/TOKEN/mail
Replace TOKEN with the token obtained using the multibroker's --print-url. Use https:// with a trusted, matching certificate.
The lsub tool lists subscribed mailboxes; mailboxes lists all visible mailboxes. Subscriptions affect folder selection in clients, not message delivery or permissions. See "Read and organize mail" in AnyEvent::MCP::Intro for search and safety examples.
TOOLS
- mailboxes
-
List visible mailboxes. The
mailboxesresult contains triples of[attributes, hierarchy_separator, name]. One entry might be[["\\HasNoChildren"], "/", "INBOX"]. Mailboxes marked\\Noselectare containers, not selectable message folders. - lsub
-
List subscribed mailboxes (IMAP LSUB). Uses the same result format as
mailboxes. - messages
-
List at most 100 message summaries, newest UID first. Optional SEARCH filter, summary fields, header names and UIDVALIDITY-aware cursor.
incompletemeans the search reached its 20000-UID scan budget: continue withnext_cursoreven if the page contains no messages.filtercombines its keys with AND. Text search keys arefrom,to,cc,bcc,subject,bodyandtext(headers and body).headermaps header names to search strings. Date keys aresince,before,on,sent_since,sent_beforeandsent_on, with dates asD-Mon-YYYY.since/before/onuse the IMAP internal date;sent_*keys use the message's Date header.largerandsmallerfilter by message size. Boolean flags includeseen,unseen,answered,unanswered,flagged,unflagged,deleted,undeleted,draft,undraft,recent,oldandnew.allandanycontain arrays of nested filters (AND and OR);notcontains one nested filter. For example:{ "mailbox": "INBOX", "limit": 20, "filter": { "since": "1-Nov-2026", "any": [ {"from": "alice@example.net"}, {"subject": "invoice", "body": "overdue"} ], "not": {"flagged": true} } }The example finds messages with an internal date since November 1 from Alice or containing both invoice in the subject and overdue in the body, excluding flagged mail. Filter nesting and size are bounded; search values are explicitly quoted as IMAP arguments, never interpolated into raw SEARCH commands.
- message
-
Read ENVELOPE, flags, dates, size and MIME BODYSTRUCTURE for a UID. Use the
uidvalidityanduidreturned bymessagesfor the selected mailbox. For example, if the current UIDVALIDITY is 13 and the UID is 42:{"mailbox": "INBOX", "uidvalidity": "13", "uid": 42} - part
-
Read a MIME part using BODY.PEEK with a byte ceiling. Returns Base64 raw transferred bytes;
decode_textadditionally decodes complete text parts using MIME transfer encoding and charset. - raw
-
Read raw RFC 5322 message bytes (bounded, Base64). Never sets Seen.
- flags
-
Add/remove a set of IMAP flags, including Deleted (but never expunge).
- copy, move
-
Copy or move named UIDs. MOVE requires server MOVE capability and has no unsafe emulation.
- append
-
APPEND a Base64-encoded RFC 5322 message up to 1 MiB. Use CRLF line endings. Reject unescaped mbox From_ separator-like lines in the raw message unless
--allow-mbox-fromis set. Refusal identifies the raw line number and explains the mboxo hazard. This uploads bytes unchanged; it is not an SMTP send operation. - expunge
-
Permanently expunge explicitly named deleted UIDs when UIDPLUS is available, or all Deleted messages in the selected mailbox when
uidsis omitted. Never fall back from UID EXPUNGE to whole-mailbox EXPUNGE. - mailbox
-
Create, rename, delete, subscribe or unsubscribe a mailbox.
PERMISSIONS
The independent profile is imap-NAME, with read, modify, manage and expunge actions. Each tool checks permission before network activity. Mailbox-specific operations can be approved for one mailbox or all mailboxes; mailboxes and lsub list folders without selecting a mailbox. This worker is NOT filesystem- or network-sandboxed; permissions authorize operations, not OS-level confinement.
OPTIONS
Shared switches are documented in "COMMON COMMAND-LINE OPTIONS" in AnyEvent::MCP::Server::Simple. The following switches are specific to mcp-imap.
- --ask MODE
-
Choose where permission prompts appear:
helper(default when run independently) uses a local helper;ttyandyadforce those local interfaces without fallback.mcpdelegates prompts to the MCP client;autouses client elicitation when advertised and otherwise falls back to the helper. A server spawned by a multibroker defaults tomcpso the broker can present its prompts. - --allow-mbox-from
-
Allow APPEND messages with unescaped mbox From_ separator-like lines. Unsafe with mboxo servers which fail to escape these lines. Off by default; can only be enabled by the server operator, not through an MCP tool.
- --provider-file FILE
-
Use FILE as a local Thunderbird OAuth JavaScript source with the
providerscommand. Invalid for normal server startup orlogin. - --ispdb-file FILE
-
Use FILE as a local Thunderbird autoconfiguration XML source with the
providerscommand. Invalid for normal server startup orlogin.