NAME

mcp-imap - inspect and manage one IMAP account through MCP

SYNOPSIS

mcp-imap [OPTION]...
mcp-imap [OPTION]... login [server HOST] [user USER] [tls ssl|starttls] [port PORT]

DESCRIPTION

Each --name is one IMAP account and one independent MCP permission profile. Run mcp-imap --name doom login server doom user root tls starttls to configure the account; then start mcp-imap --name doom --stdio or its usual HTTP listener. Login asks for a password on the controlling terminal without echo. It never accepts passwords on the command line or through an MCP tool.

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. No OAuth or insecure cleartext IMAP login is implemented.

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.

TOOLS

mailboxes

List visible mailboxes.

messages

List at most 100 message summaries, newest UID first. Optional SEARCH filter, summary fields, header names and UIDVALIDITY-aware cursor. incomplete means the search reached its 20000-UID scan budget: continue with next_cursor even if the page contains no messages.

message

Read ENVELOPE, flags, dates, size and MIME BODYSTRUCTURE for a UID.

part

Read a MIME part using BODY.PEEK with a byte ceiling. Returns Base64 raw transferred bytes; decode_text additionally 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-from is 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 uids is 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. Approval applies to the selected mailbox or all mailboxes. This worker is NOT filesystem- or network-sandboxed; permissions authorize operations, not OS-level confinement.

OPTIONS

Common options: "mcp_getoptions" in AnyEvent::MCP::Server::Simple, including --name, --stdio, --connect, --print-url, --auto-allow, --auto-deny and --tool-help.

--ask MODE

Choose permission prompting: helper (default), tty, yad, mcp or auto.

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