163 Mail MCP

A privacy-first local MCP server for a personal @163.com mailbox. It connects directly to 163 Mail over IMAP/SMTP, keeps the client authorization code in macOS Keychain, and exposes typed tools to Codex and Claude over local stdio.

Safety model

• Search and reading use read-only IMAP access; message reads use BODY.PEEK.
• Every send, move, trash, attachment download, or read-state change requires an exact confirmation token.
• Sending additionally requires a digest from the complete draft preview and rejects changed bodies or attachments.
• Batch moves, Trash moves, and read-state changes require a complete preview plus a SHA-256 digest. The server rechecks all messages before attempting the first write.
• “Trash” means copy to a confirmed Trash folder and mark the source \Deleted; the server never sends EXPUNGE.
• Downloaded attachments never overwrite existing files.
• Mail content is treated as untrusted data, not as instructions.

The server is currently macOS-only because credentials are stored with the macOS security command. Account metadata is stored under ~/.config/163-mail-mcp/; secrets and mail content are never written to this repository.

Install

Requirements: macOS, Python 3.10 or newer, and uv.

git clone https://github.com/adjurtime/163-mail-mcp.git
cd 163-mail-mcp
uv sync --python 3.12

Enable 设置 → POP3/SMTP/IMAP → IMAP/SMTP 服务 in 163 webmail. Then configure the account in your own Terminal so the authorization code does not enter chat or logs:

.venv/bin/mail163 configure --email name@163.com
.venv/bin/mail163 status --json

Existing users of the earlier codex-163-mail Keychain/config identifiers are detected automatically. Running configure again writes the new 163-mail-mcp identifiers.

Register the MCP server

Use absolute paths in client configuration. From the repository root:

codex mcp add 163-mail-mcp -- "$PWD/.venv/bin/163-mail-mcp"
claude mcp add --scope user 163-mail-mcp -- "$PWD/.venv/bin/163-mail-mcp"

Restart the client or open a new task after registration.

Optional Codex skill

The paired Skill adds workflow guidance and confirmation rules. Link it into the Codex skills directory from the repository root:

mkdir -p "$HOME/.codex/skills"
ln -s "$PWD/skills/163-mail-mcp" "$HOME/.codex/skills/163-mail-mcp"

Tools

Tool	Purpose	Write guard
mail_status	Check configuration and IMAP authentication	Read-only
list_folders	List folders	Read-only
search_mail_headers	Search headers without bodies	Read-only
read_mail	Read one message without setting Seen	Read-only
preview_send	Validate and preview an outgoing draft	Read-only
send_mail	Send the unchanged previewed draft	SEND + digest
preview_batch_actions	Preview and summarize 1–50 move, Trash, or read-state actions	Read-only
execute_batch_actions	Recheck and execute the unchanged previewed batch	BATCH + digest
move_mail	Move one UID	MOVE
trash_mail	Move one UID to confirmed Trash	TRASH
download_attachments	Save selected attachments without overwrite	DOWNLOAD
set_read_state	Mark one UID read or unread	MARK

Tool annotations help clients present risk, but the core enforces all guards independently.

Test

Tests use fakes and temporary files; they do not connect to a mailbox or send mail.

uv run python -m unittest discover -s tests -v

License

MIT