Content
# Tool List
Mail Plug 메일을 Claude에서 **잘 쓰고, 깨지지 않게 보내고, 받은 편지함을 검색·읽는** MCP 서버.
## 1. Why is this needed?
- New Outlook for Mac has compatibility issues with Mail Plug IMAP, causing account addition to fail (Microsoft Cloud verification stage failure).
- Using a general email client like Apple Mail prevents Claude from accessing that email.
- Even using the Microsoft 365 connector requires synchronizing company email with Microsoft Cloud, and sending emails is not possible under the name you@example.com.
This MCP precisely bridges that gap — Claude sends directly to Mail Plug via SMTP and receives via IMAP. No intermediate cloud, no external service, and no password server storage.
## 2. Tool List
| Tool | Description |
|------|------|
| `draft_email` | Renders markdown body into inline CSS HTML and returns a preview. **Does not send.** |
| `send_draft` | Sends a draft created with `draft_id`. `confirmed=True` is required. |
| `discard_draft` | Discards a draft without sending it. |
| `list_drafts` | Lists drafts waiting to be sent. |
| `list_inbox` | Lists envelope items in the inbox (newest first). |
| `search_email` | Searches for keywords (including Korean). |
| `get_email` | Retrieves a single email body (plain+html) + attachment metadata. |
| `download_attachment` | Saves an attachment file locally. |
| `list_folders` | Lists IMAP folder names (for user folder name confirmation). |
Sending is **only possible in two steps** (draft → user confirmation → send), structurally preventing Claude from sending alone.
## 3. System Requirements
- macOS 12+ / Windows 10+ / Linux (any OS with a keyring backend)
- Python 3.10 or higher
- Mail Plug account + app password (Mail Plug webmail → Settings → Login Security Settings → App Password)
- Mail Plug IMAP/SMTP usage enabled (Settings → Mail → IMAP tab)
## 4. Installation
### (a) Using `uv` — recommended
```bash
# repo clone + dependency installation + virtual environment in one go
git clone https://github.com/YOUR-USERNAME/mailplug-mcp.git
cd mailplug-mcp
uv venv
uv pip install -e ".[dev]"
```
### (b) Using `pip`
```bash
git clone https://github.com/YOUR-USERNAME/mailplug-mcp.git
cd mailplug-mcp
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```
After installation, two commands are registered in PATH:
- `mailplug-mcp` — MCP server main body (called by Claude)
- `mailplug-mcp-setup` — one-time settings for keychain storage / signature import, etc.
## 5. One-time Setup
### 5.1 Environment Variables
Copy `.env.example` to `.env` and fill in your information. **Never write passwords in `.env`.**
```bash
cp .env.example .env
```
Edit the required items:
```env
MAILPLUG_EMAIL=you@example.com
MAILPLUG_DISPLAY_NAME=John Doe
MAILPLUG_SIGNATURE_MODE=auto
MAILPLUG_SIGNATURE_NAME=John Doe
MAILPLUG_SIGNATURE_TITLE=Position
MAILPLUG_SIGNATURE_COMPANY=Company Name
MAILPLUG_SIGNATURE_PHONE=010-0000-0000
MAILPLUG_SIGNATURE_WEBSITE=example.com
```
### 5.2 App Password Keychain Storage
```bash
mailplug-mcp-setup
# Mail Plug email address [you@example.com]: ↵
# App password: (not displayed during input)
# ✓ you@example.com's app password has been stored in the keychain.
```
Storage location:
- macOS: Keychain Access → "mailplug-mcp" item
- Windows: Credential Manager → "mailplug-mcp" item
- Linux: Secret Service (GNOME Keyring / KWallet)
Change password: Run the same command again → overwrite.
Delete: `mailplug-mcp-setup --reset --email you@example.com`.
### 5.3 (Optional) Importing Mail Plug Signature
To operate with `MAILPLUG_SIGNATURE_MODE=mailplug` or `auto`, import your Mail Plug signature HTML once:
1. Mail Plug webmail → Settings → Mail → Signature → edit your signature → click "HTML view" → save the displayed HTML in a file (`signature.html`).
2. Register the cache with the following command:
```bash
mailplug-mcp-setup --import-signature signature.html
```
Cache location: `~/.mailplug-mcp/signature_cache.json`
If `signature_mode=auto`, it will use this cache first; if not, it will generate a template signature using `.env` values.
## 6. Registration with Claude Desktop / Claude Code
### 6.1 Claude Desktop (`claude_desktop_config.json`)
macOS location: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mailplug": {
"command": "/absolute/path/mailplug-mcp/.venv/bin/mailplug-mcp",
"env": {
"MAILPLUG_EMAIL": "you@example.com",
"MAILPLUG_DISPLAY_NAME": "John Doe",
"MAILPLUG_SIGNATURE_MODE": "auto",
"MAILPLUG_SIGNATURE_NAME": "John Doe",
"MAILPLUG_SIGNATURE_TITLE": "Position",
"MAILPLUG_SIGNATURE_COMPANY": "Company Name",
"MAILPLUG_SIGNATURE_PHONE": "010-0000-0000",
"MAILPLUG_SIGNATURE_WEBSITE": "example.com"
}
}
}
}
```
Verify the `command` path with `which mailplug-mcp`. Use the absolute path of the virtual environment.
### 6.2 Claude Code
Add the same block to the workspace root's `.mcp.json` or the user's global `~/.claude/mcp.json`.
### 6.3 Cowork Mode
Cowork operates on Claude Desktop, so it's the same as 6.1.
After setting up, restart Claude, and 9 `mp_*` tools will appear in the tool list.
## 7. Usage Examples
### 7.1 Sending
> User: "Send an email to boss@example.com with the subject 'Weekly report attached'. The body should summarize the three key points of this week, one line each, and then list the next week's schedule in two lines."
Claude calls `draft_email` → displays a preview → asks the user for confirmation → calls `send_draft(confirmed=True)` → sends the email.
### 7.2 Receiving and Searching
> User: "Find the email I received from Kim, Taeyoung this week"
Claude calls `search_email(query="Kim Taeyoung", limit=20)` → shows 5 envelope results → user selects one → uses `get_email(uid=...)` to expand the body.
### 7.3 Attachment Download
> User: "Save the PDF attached to that email on my desktop"
`download_attachment(uid=..., attachment_index=2, save_to="~/Desktop/report.pdf")`.
## 8. Security Model
- App passwords are stored only in the OS keychain. Never in code, git, or configuration files.
- The company does not store employee passwords (each stores their own).
- Sending is only possible with the explicit `confirmed=True` flag (preventing automatic sending accidents).
- Received email bodies are in Claude's context but not used as external learning data (Anthropic policy).
- Bcc addresses are included only in the SMTP envelope (RFC 5321 / 5322 standard).
- TLS uses SSLContext.create_default_context() defaults for both SMTP_SSL(465) and IMAP_SSL(993) — activates certificate verification and blocks weak ciphers.
## 9. Troubleshooting
| Symptom | Cause / Action |
|------|------------|
| `RuntimeError: MAILPLUG_EMAIL is not set` | Write `.env` and restart Claude. Directly using the env block in Claude Desktop is also OK. |
| `CredentialError: No app password found in keyring` | Run `mailplug-mcp-setup`. If already done, check if the `--email` argument matches. |
| SMTP `Authentication failed` | (1) Check Mail Plug → Settings → IMAP usage is ON, (2) reissue app password and re-run setup. |
| IMAP `login failed` | Same as above. If SMTP works but IMAP fails, often the general password is incorrect. |
| HTML is broken on the recipient's side | Check with `tests/test_renderer.py`, report issues. If premailer inline omission is suspected, create an issue. |
## 10. Development
```bash
pytest # Run tests
ruff check src tests # Static analysis
ruff format src tests # Formatting
```
## 11. License
MIT — refer to `LICENSE`.
