163 Mail MCP
# 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](https://docs.astral.sh/uv/).
```bash
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:
```bash
.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:
```bash
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:
```bash
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.
```bash
uv run python -m unittest discover -s tests -v
```
## License
MIT
TDQS
Scored across 12 tools
Most tools are clearly distinct: reading, sending, trashing, moving, search, and batch operations each target different actions. However, move_mail, trash_mail, set_read_state individually overlap conceptually with their batch counterparts, and preview_send/send_mail plus preview_batch_actions/execute_batch_actions form pairs that could cause mis-selection if an agent isn't careful about which stage is needed.
Tools follow a consistent verb_noun pattern (list_folders, read_mail, send_mail, trash_mail, move_mail, download_attachments, set_read_state, mail_status). A minor deviation exists with search_mail_headers and the pair preview_batch_actions/execute_batch_actions, which use a descriptive phrase style rather than a single verb, but the overall naming is coherent and predictable.
At 12 tools, the count is reasonable for a mail MCP server covering read, search, send, move, trash, mark, attachment, batch, and status operations. It sits slightly above the ideal core set but each tool serves a distinct function; a couple of tools could theoretically be merged (e.g., single-action operations could be covered by batch), but the count is well within acceptable bounds.
The surface covers core mailbox operations: listing folders, status, searching, reading, sending, moving, trashing, marking read state, batch operations, and attachments. Minor gaps include no explicit compose/save-draft tool (preview_send acts as a proxy), no message-level threading/folder management (create/delete folders), and no way to fetch full content beyond a single message, but the main workflows are covered without dead ends.