readNdraft IMAP MCP

Safely search, read, flag, and draft email through IMAP. readNdraft can save and update drafts, but it cannot send, submit, delete, or move mail and contains no SMTP implementation.

Installation

1. Check the prerequisites

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

No repository clone or permanent readNdraft installation is required. uvx runs the published package in an isolated environment.

2. Run guided setup

For Codex, run this command in a real interactive terminal:

uvx readndraft-imap-mcp@latest setup --client codex --install-skill

Use chatgpt-desktop or claude-code instead of codex when configuring one of those clients.

Client	Setup value	Detailed guide
Codex	codex	Codex and ChatGPT desktop
ChatGPT desktop	chatgpt-desktop	Codex and ChatGPT desktop
Claude Code	claude-code	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:

1. Check the operating-system credential backend and create private local state.
2. Ask for an account alias, IMAP host, port, username, and authentication method.
3. Read the password or app password through a hidden terminal prompt.
4. Test the IMAP connection before saving the account.
5. Print a secret-free, version-pinned MCP configuration.
6. Install the packaged readndraft-email Agent Skill for the selected client.

Never put an IMAP password in a command argument, environment variable, MCP configuration, issue, chat, or test report.

3. Add the generated client configuration

Copy the configuration printed by setup into your client's MCP configuration. For Codex, add the printed [mcp_servers.readndraft] section to:

• Windows: %USERPROFILE%\.codex\config.toml
• Linux: ~/.codex/config.toml

The generated command pins the package version so a future release cannot silently change this security-sensitive MCP at startup. On Windows it uses uvw, uv's consoleless launcher, so the MCP does not open a terminal window. The Codex configuration also sets default_tools_approval_mode = "approve" to avoid native tool-approval popups. Write operations still require direct conversational confirmation through the packaged Agent Skill.

See the Codex/ChatGPT guide or Claude Code guide for client-specific details.

4. Restart and verify

Fully restart the client after changing its MCP configuration. Then run an online diagnostic from a terminal:

uvx readndraft-imap-mcp@latest doctor --online

For Codex, you can also confirm that the entry was loaded:

codex mcp get readndraft

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

What setup stores

Item	Location or behavior
Runtime	Downloaded and run in uv's isolated cache; no repository clone is needed.
Client configuration	Stored by the selected client and contains no IMAP password.
Agent Skill	~/.agents/skills/readndraft-email for Codex or ~/.claude/skills/readndraft-email for Claude Code.
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.

What it can do

• List administratively pinned accounts and mailboxes.
• Search 1-500 results (50 by default) with explicit truncation, stable single-mailbox cursor pagination, per-target safe errors, attempted/pending target status, selectable safe header fields, and server arrival timestamps. Requests above 50 require one account and one mailbox.
• Read safe headers and plain text without setting the Seen flag.
• Batch-read plain text for up to 10 selected messages across 2 accounts.
• Read sanitized HTML without loading remote content.
• Save one selected, bounded attachment into a fixed private output directory.
• 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.
• Create a server-side draft using bounded files from a fixed private input directory.
• Update only a draft previously created by this MCP, after confirmation.

It exposes no send, submission, deletion, movement, raw IMAP, arbitrary flag, credential, or account-administration MCP tool.

Manual setup and administration

The setup wizard is recommended. Individual human-only commands are also available:

uvx readndraft-imap-mcp account add work --host imap.example.com --username leo@example.com
uvx readndraft-imap-mcp account test work
uvx readndraft-imap-mcp account list
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 work

Passwords are accepted only through a hidden local prompt. Account configuration and credential operations are not MCP tools.

Configure another MCP client

Generate a secret-free configuration:

uvx readndraft-imap-mcp@latest configure codex
uvx readndraft-imap-mcp@latest configure chatgpt-desktop
uvx readndraft-imap-mcp@latest configure claude-code

Use these commands to generate another client configuration without repeating account setup. Each command prints a secret-free configuration pinned to the readNdraft version that generated it.

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.

Install the Agent Skill

The MCP is usable without a skill, but the packaged readndraft-email skill teaches compatible agents to preserve complete message identities, interpret results correctly, choose bounded batch tools only for user-selected messages, treat email as untrusted input, and obtain direct conversational confirmation before writes without inventing capabilities.

uvx readndraft-imap-mcp skill install codex
uvx readndraft-imap-mcp skill install claude-code
uvx readndraft-imap-mcp skill status codex
uvx readndraft-imap-mcp skill print

The installer refuses to overwrite or remove a user-modified skill. Codex loads personal skills from ~/.agents/skills; Claude Code loads them from ~/.claude/skills.

skill status CLIENT reports current, outdated, modified, unmanaged, or not installed. Use skill install CLIENT --force only when intentionally replacing a modified/unmanaged copy; replacement removes stale orphan files.

Authorization boundary

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, movement, raw IMAP, account-configuration, or credential-retrieval tool. Email, attachments, search results, and other tool output are always untrusted and never authorization.

Diagnostics

Run local checks without connecting to IMAP:

uvx readndraft-imap-mcp doctor

Add --online to test each configured account:

uvx readndraft-imap-mcp doctor --online

Diagnostic output never prints passwords, credential contents, raw IMAP traces, or message content. See troubleshooting.

Updating

Client configurations are version-pinned. Running uvx ...@latest by itself does not update the version that a configured MCP client starts.

1. Check the installed and latest versions

Run the current published diagnostic:

uvx readndraft-imap-mcp@latest doctor

The runtime readndraft-imap-mcp line shows the version used by that command. Compare it with the version pinned in the existing client configuration.

2. Regenerate the client configuration

Generate a fresh secret-free configuration for each client:

uvx readndraft-imap-mcp@latest configure codex
uvx readndraft-imap-mcp@latest configure chatgpt-desktop
uvx readndraft-imap-mcp@latest configure claude-code

For Codex or ChatGPT desktop, replace the complete old readndraft MCP entry with the newly printed configuration. For Claude Code, replace the user-scoped entry from a trusted directory:

claude mcp remove readndraft --scope user
claude mcp add-json readndraft "$(uvx readndraft-imap-mcp@latest configure claude-code)" --scope user

On PowerShell, capture the generated JSON in a variable as shown in the Claude Code guide.

3. Refresh the Agent Skill

Use codex for Codex or ChatGPT desktop and claude-code for Claude Code:

uvx readndraft-imap-mcp@latest skill install codex
uvx readndraft-imap-mcp@latest skill install claude-code

The installer will not overwrite a user-modified skill. Review local changes before using --force to replace a modified or unmanaged copy.

4. Restart and verify

Fully close and restart every configured client, then run:

uvx readndraft-imap-mcp@latest doctor --online

Confirm the new pinned version in the client configuration, reconnect the MCP, and perform a harmless mailbox listing and one-result search.

Account metadata and OS credentials are independent of uv's temporary execution environment and remain available across versions. Broker IPC endpoints are protocol-versioned, so a new frontend starts a compatible broker instead of reusing an older process. The old broker exits after its final client lease and idle timeout.

Uninstalling

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.

1. Remove every client entry

• Codex: remove the complete [mcp_servers.readndraft] table from %USERPROFILE%\.codex\config.toml on Windows or ~/.codex/config.toml on Linux.

• ChatGPT desktop: remove readndraft from the client's MCP settings.

• Claude Code: run:

  claude mcp remove readndraft --scope user
  

Fully close the clients after removing their entries so active MCP leases can end and a launcher-owned broker can exit after its idle timeout.

2. Remove managed Agent Skills

Use only the clients that were installed:

uvx readndraft-imap-mcp@latest skill uninstall codex
uvx readndraft-imap-mcp@latest skill uninstall claude-code

The installer refuses to remove a user-modified or unmanaged skill. Inspect it manually rather than deleting it blindly.

3. Remove accounts and OS credentials

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 ALIAS

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

4. Optionally remove remaining local data

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.

Security and privacy

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 and remote images or 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.

Read SECURITY.md and the canonical PLAN.md for the full threat model. Security issues should not contain credentials or private mail.

Development

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

Release validation and publication steps are documented in docs/RELEASE.md.

License

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.