Safely manage IMAP email without sending or deleting ordinary mail: discover accounts/mailboxes, search and read messages, handle attachments, draft emails, change flags, and move messages within safety constraints.
List account aliases and exact mailboxes for 1–10 accounts with isolated failures.
Search 1–500 email metadata rows with filters, stable paging, selected headers, and per-target status.
Read safe headers and plain text for one email or batches up to 10; read sanitized HTML without remote loading.
List attachment input files and save one selected attachment to a fixed private output directory.
Create plain-text or rich HTML drafts with optional fixed-directory attachments, CC/BCC, and reply threading.
Update only drafts previously created by this MCP; no send capability.
Star/unstar and mark read/unread individually or in batches up to 50.
Move one or up to 50 messages within one account between ordinary mailboxes; special-use Trash/Junk/Drafts/Sent moves are prohibited.
No SMTP/send, ordinary-message deletion, raw IMAP, arbitrary flag, credential, or account-administration MCP tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@readNdraft IMAP MCP Find unread emails from my boss about the Q3 report and draft a response."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Safely search, read, flag, move, and draft email through IMAP. readNdraft can save and replace MCP-created drafts, but it cannot send, submit, or delete ordinary mail and contains no SMTP implementation.
You need:
Windows 10/11 with Windows Credential Manager, or Linux with a working Secret Service-compatible keyring.
An IMAP account that permits password or app-password authentication using
LOGIN or PLAIN over implicit TLS. OAuth is not implemented.
uv on PATH.
Codex, ChatGPT desktop, or Claude Code.
Confirm that uv is available:
uv --versionNo repository clone or permanent readNdraft installation is required. uvx
runs the published package in an isolated environment.
Run guided setup in a real interactive terminal:
uvx readndraft-imap-mcp@0.12.2 setupThis configures only readNdraft's local account, credential, and private state. Claude Code and Codex own their plugin, MCP registration, updates, and removal. ChatGPT desktop remains a separate manual MCP configuration target.
Client | Setup value | Detailed guide |
Codex |
| |
ChatGPT desktop |
| |
Claude Code |
|
Linux users should also follow the Linux platform guide to verify Secret Service and D-Bus before setup. Windows users can use the Windows platform guide.
The wizard will:
Check the operating-system credential backend and create private local state.
Ask for an account alias, IMAP host, port, username, and authentication method.
Read the password or app password through a hidden terminal prompt.
Test the IMAP connection before saving the account.
Never put an IMAP password in a command argument, environment variable, MCP configuration, issue, chat, or test report.
The repository is the marketplace source; this is not GitHub Marketplace.
For Codex:
codex plugin marketplace add LeoPhoenixT/readNdraft-imap-mcp
codex plugin add readndraft@readndraftFor Claude Code, run these commands inside Claude Code:
/plugin marketplace add LeoPhoenixT/readNdraft-imap-mcp
/plugin install readndraft@readndraftThe plugin supplies one shared readndraft-email skill and a local stdio MCP
definition pinned to readndraft-imap-mcp@0.12.2. It does not contain secrets,
account data, or a send capability.
Start a new client session after installing the plugin. Then run an online diagnostic from a terminal:
uvx readndraft-imap-mcp@latest doctor --onlineFor Codex, you can also confirm that the entry was loaded:
codex mcp get readndraftOpen a new task and ask: List my readNdraft accounts and mailboxes. A
successful response confirms that the client can start the MCP and reach the
local broker.
Item | Location or behavior |
Runtime | Version-pinned by the plugin and run in uv's isolated cache. |
Client integration | Marketplace/plugin state owned by Claude Code or Codex; it contains no IMAP password. |
Agent Skill |
|
IMAP password | Stored only in Windows Credential Manager or the Linux Secret Service keyring. |
Account metadata and app state | Stored in private per-user readNdraft application directories. |
If setup reports a credential-backend or connection error, see
Windows installation,
Linux installation, and
troubleshooting.
The first MCP start may take longer
while uv downloads the pinned package. If a stored password has changed, run
uvx readndraft-imap-mcp account rotate-secret ALIAS.
Related MCP server: mailgate
List administratively pinned accounts and mailboxes.
Search 1-500 results (50 by default) with explicit truncation, stable
single-mailbox cursor pagination, per-target complete, partial, error,
or pending status, attempted/pending legacy fields, selectable safe header
fields, and server arrival timestamps. Attachment filename matching uses
bounded MIME BODYSTRUCTURE metadata, never downloaded attachment payloads.
Requests above 50 require one account and one mailbox.
Read safe headers and preferred plain text without setting the Seen flag.
HTML-only messages are converted into a bounded, readable plain-text
representation; get_email_html remains available for sanitized rich HTML.
When the server supplies a valid MIME BODYSTRUCTURE, these reads fetch only
the selected text section; malformed or nested-message structures use the
existing bounded full-message fallback.
Batch-read plain text for up to 10 selected messages across 2 accounts.
Read strictly filtered HTML without loading remote content; remote-resource elements, attributes, and CSS are removed, and empty paragraphs are preserved.
Save one selected, bounded attachment into a fixed private output directory and
return its absolute native-platform path. Attachment listings report nullable
decoded size until a selected attachment is downloaded, plus nullable IMAP
transfer-encoded encoded_size when BODYSTRUCTURE or exact wire bytes are known.
Star/unstar and mark read/unread without replacing unrelated flags.
Batch one star or read state across up to 50 selected messages and 3 accounts; batches return ordered per-item results.
Move one or up to 50 selected messages within one account. The broker prefers
native UID MOVE and otherwise uses a private UIDPLUS COPY, source-only
\Deleted, and targeted UID EXPUNGE sequence. Both source and destination
must be existing selectable ordinary mailboxes; movement into or out of
\Trash, \Junk, \Drafts, or \Sent SPECIAL-USE mailboxes is prohibited.
Create a plain-text or rich HTML server-side draft using bounded files from a
fixed private input directory. Rich drafts require equivalent body plain
text and optional html_body HTML. They are stored as
multipart/alternative, with plain text first and HTML second, so modern mail
clients normally display HTML while other clients retain a plain fallback.
Rich input may be an HTML fragment or a complete HTML document. Supported
authored CSS is permissive and inlined for broad mail-client compatibility.
Draft requests are rejected when CSS could fetch remote resources, hide
content, or escape the message box; empty paragraphs are always preserved.
To, Cc, and Bcc may all be empty when the user wants an unaddressed draft.
Each list item is one bare or named mailbox (for example, Ada <ada@example.com>).
create_draft may receive an exact source message identity as reply_to_message
to add safe reply threading; it does not derive recipients or rewrite subjects.
Update only a draft previously created by this MCP, after confirmation.
Inspect and repair local draft tracking with drafts list and drafts repair.
drafts forget removes only the local tracking record; it never deletes or
expunges the server message.
It exposes no send, submission, ordinary-message deletion, raw IMAP, arbitrary
flag, credential, or account-administration MCP tool. Updating a tracked draft
replaces it and expunges the previous draft version. A successful move reports
its method and invalidates the source identity. Native MOVE may succeed without
COPYUID, leaving the destination identity unavailable. The fallback requires
COPYUID before marking the source deleted; otherwise it reports partial_move,
retains the source, and requires both mailboxes to be reviewed. Never
automatically retry an ambiguous move outcome.
The setup wizard is recommended. Individual human-only commands are also available:
uvx readndraft-imap-mcp account add work --host imap.example.com --username login@imap.example.com --sender-address user@example.com --sender-name "Display Name"
uvx readndraft-imap-mcp account test work
uvx readndraft-imap-mcp account list
uvx readndraft-imap-mcp account set-sender work leo@example.com
uvx readndraft-imap-mcp account clear-sender work
uvx readndraft-imap-mcp account set-sender-name work "Display Name"
uvx readndraft-imap-mcp account clear-sender-name work
uvx readndraft-imap-mcp account rotate-secret work
uvx readndraft-imap-mcp account disable work
uvx readndraft-imap-mcp account enable work
uvx readndraft-imap-mcp account delete workPasswords are accepted only through a hidden local prompt. Account configuration
and credential operations are not MCP tools. username is the IMAP login identity;
sender_address is the bare email address placed in the draft's From header and
may differ from that username. If omitted or cleared, the address falls back to the
username. sender_name is an optional display name, producing a header such as
From: "Display Name" <user@example.com>; clearing it restores address-only
behavior. MCP list_accounts exposes both effective sender settings so an agent can
confirm them, but MCP cannot change or override them per draft. Downstream SMTP
servers, mailing lists, and other mail systems may rewrite headers after the draft
leaves the client; the MCP controls only the MIME draft it creates.
Generate a secret-free configuration:
uvx readndraft-imap-mcp@latest configure chatgpt-desktopThis manual configuration path is retained for ChatGPT desktop, which is not
covered by the Claude Code/Codex marketplace migration. The configure codex
and configure claude-code forms remain temporarily available only for legacy
0.3.x compatibility and are not the normal installation path.
The unified mcp command uses the authenticated on-demand launcher. It reuses a
healthy broker, starts exactly one when needed, and holds an authenticated lease
while the MCP frontend is connected. A launcher-owned broker exits only after
the final frontend disconnects and the idle period expires. Always-on systemd
and Windows scheduled-task deployments remain available through the legacy
administration documentation.
The broker has no approval-token workflow. Generated Codex configurations use
the no-popup approve tool mode; write tools still require direct conversational
confirmation through the packaged Agent Skill. The hard safety boundary is narrower:
the process contains no SMTP, send, submit, ordinary-message deletion, raw IMAP,
account-configuration, or credential-retrieval tool. Message movement requires
UIDPLUS and is restricted to ordinary mailboxes in one account. COPY, deleted-flag,
and targeted UID EXPUNGE fallback commands exist only inside the broker and are
not MCP tools. Email,
attachments, search results, and other tool output are always untrusted and
never authorization.
Run local checks without connecting to IMAP:
uvx readndraft-imap-mcp doctorAdd --online to test each configured account:
uvx readndraft-imap-mcp doctor --onlineDiagnostic output never prints passwords, credential contents, raw IMAP traces, or message content. See troubleshooting.
Before updating, review the upgrade guide for the migration steps that apply to your installed version. Installations from 0.3.x or earlier need a one-time migration to the marketplace plugin. See the changelog for release changes.
Use the client's native marketplace/plugin update command. Plugin release, Claude manifest, Codex manifest, and pinned PyPI runtime versions are validated as one compatibility unit. Start a new session after an update, then run:
uvx readndraft-imap-mcp@latest doctor --onlineAccount metadata and OS credentials remain independent of the plugin lifecycle.
Choose whether to remove only the MCP integration or all local readNdraft data. Removing client entries and skills leaves accounts, credentials, audit history, draft provenance, and attachment exchange files available for a later reinstall.
Use the client-native plugin uninstall command. The plugin-provided MCP and
skill disappear together. If this installation was upgraded from 0.3.x and the
one-time migration has not been run, run migrate-plugin first so no old direct
MCP entry remains. Remove a ChatGPT desktop entry separately in that client's
MCP settings.
Fully close the client afterward so active MCP leases can end and a launcher-owned broker can exit after its idle timeout.
Skip this step when retaining accounts for a later reinstall. For a complete removal, list accounts and delete each alias through the interactive command:
uvx readndraft-imap-mcp@latest account list
uvx readndraft-imap-mcp@latest account delete ALIASaccount delete requires exact confirmation and removes the corresponding
password or app password from Windows Credential Manager or the Linux Secret
Service keyring. Do this before manually deleting application state; otherwise
the account metadata needed to identify a stored credential may be lost.
Run uvx readndraft-imap-mcp@latest doctor to display the private state path and
uvx readndraft-imap-mcp@latest attachments path to display the fixed attachment
exchange directories. Inspect them before manually removing anything. Remaining
data can include:
integrity-chained audit history;
draft provenance needed to update MCP-created drafts;
downloaded and upload-staging attachments;
the local IPC key and broker state;
an unused approvals directory left by an older build.
Remove these directories only when their audit, recovery, and attachment data is no longer needed. readNdraft does not delete them automatically.
There is no permanently installed uv tool to uninstall when readNdraft is used
only through uvx. uv may retain ordinary download/build cache entries shared
with other tools; clearing uv's global cache is not required to uninstall
readNdraft.
The stdio MCP frontend cannot read the account file or OS credential store. It
communicates over authenticated per-user IPC with a separate broker that enforces
capabilities, quotas, provenance, and audit. Email and attachments are always
untrusted input. Received HTML is sanitized for rich reads while preserving
useful email structure, safe links, and a conservative set of presentation
styles; HTML-only mail is converted to plain text for normal reads. Draft HTML
is also sanitized and normalized before storage. It accepts common modern email
markup, complete HTML documents, safe links, and allowlisted CSS; stylesheet
rules are inlined for mail-client compatibility. Active content, event handlers,
unsafe URL schemes, external stylesheets, and images cause draft creation or
update to be rejected. Remote images, stylesheets, links,
or other URLs are never fetched automatically.
MCP tools never accept arbitrary local paths: draft files come only from the
readNdraft attachment input directory and downloaded attachments are written
only to its output directory. Run readndraft-imap-mcp attachments path to
locate them. save_attachment also returns the saved file's absolute path using
the MCP server host's native path format; clients must use that value verbatim.
Read SECURITY.md for the current security boundary. Security issues should not contain credentials or private mail.
IPC 12 pins request validation, structured nested SafeError records, and
aggregate resource health data. Inspect error.code rather than matching error
message text. A draft_busy
result means another update holds the draft lock; recovery_required needs
draft recovery before retrying; outcome_unknown means the IMAP write may have
completed, so inspect the draft state instead of retrying automatically.
See CONTRIBUTING.md before proposing a change. Security reports must use the private route documented in SECURITY.md.
uv sync --extra dev
uv run pytest
uv run python scripts/security_check.py
uv build --no-sourcesRelease validation and publication steps are documented in docs/RELEASE.md.
readNdraft, including its packaged Agent Skill and documentation, is licensed under the Apache License 2.0. Dependency licensing is summarized in THIRD_PARTY_NOTICES.md.
Save a draft; authored HTML permits normal mail layout CSS but rejects remote resources, hidden content, and message-box escapes. Empty paragraphs are preserved. No send capability.
Inputs: to (required), body (required), subject (required), account_id (required), +5 more. Returns: uid, mailbox, draft_id, account_id, +3 more
Read safe headers/plain text using one complete returned identity.
Inputs: uid (required), mailbox (required), account_id (required), uid_validity (required), +1 more. Returns: text, flags, headers, identity, +3 more
Read strictly filtered HTML without remote loading; empty paragraphs are preserved.
Inputs: uid (required), mailbox (required), account_id (required), uid_validity (required). Returns: html, flags, identity
Read plain text for 1-10 exact identities with ordered partial results.
Inputs: identities (required), max_text_chars. Returns: result
List safe account aliases. Call this before using an unknown alias.
Inputs: no named parameters. Returns: result
List safe files available in readNdraft's fixed attachment input directory.
Inputs: no named parameters. Returns: result
List exact mailbox names for 1-10 accounts with isolated failures.
Inputs: account_ids (required). Returns: result
Move one ordinary message to an existing ordinary mailbox.
Inputs: uid (required), mailbox (required), account_id (required), uid_validity (required), +1 more. Returns: method, identity, destination_mailbox, destination_identity
Move 1-50 ordinary messages from one account to one mailbox.
Inputs: identities (required), destination_mailbox (required). Returns: result
Save one attachment; saved_path is its absolute native-platform location.
Inputs: uid (required), mailbox (required), account_id (required), uid_validity (required), +1 more. Returns: size, sha256, saved_name, saved_path, +2 more
Search 1-500 metadata rows in stable mailbox order with optional paging.
Inputs: targets (required), read, text, after, +9 more. Returns: order, errors, results, truncated, +4 more
Set one read state idempotently.
Inputs: uid (required), read (required), mailbox (required), account_id (required), +1 more. Returns: state, changed, enabled, identity, +2 more
Set one read state for 1-50 identities.
Inputs: read (required), identities (required). Returns: result
Set one starred state idempotently.
Inputs: uid (required), mailbox (required), starred (required), account_id (required), +1 more. Returns: state, changed, enabled, identity, +2 more
Set one starred state for 1-50 identities.
Inputs: starred (required), identities (required). Returns: result
Replace a draft; authored HTML permits normal mail layout CSS but rejects remote resources, hidden content, and message-box escapes. Empty paragraphs are preserved. No send capability.
Inputs: to (required), body (required), subject (required), draft_id (required), +5 more. Returns: uid, method, mailbox, draft_id, +4 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
Each tool has a clear, distinct purpose. Batch and single variants (e.g., set_read_state vs set_read_state_batch) are explicitly differentiated, and get_email vs get_email_html vs get_emails serve different needs. No overlapping tools could cause selection confusion.
All tool names follow a consistent verb_noun pattern with snake_case, using 'batch' as a uniform suffix for multi-item operations. Examples like list_accounts, search_emails, set_star, and create_draft are predictable and uniform.
16 tools is well-scoped for an IMAP server covering read, search, flag, move, draft, and attachment workflows. The count is neither bloated nor thin, and each tool contributes to the core functionality.
The surface covers most essential IMAP operations: reading, searching, flagging, moving, drafts, and attachments. However, there is no delete operation for emails or drafts, and no explicit trash handling, which are minor gaps for typical email workflows.
Gmail, Outlook, Hotmail, Microsoft 365, iCloud, Fastmail, other IMAP mailboxes: search, read, send.
Never-stored live email: read, send and triage Gmail, Outlook / Microsoft 365, or any IMAP mailbox.
Read, send, file and search email in any Gmail, Microsoft 365 or IMAP mailbox, plus its calendar.
Search connected email, read and manage messages, draft and send, and manage rules for new mail.
