# ai-mail-mcp

把**私人域名邮箱**接入任意 MCP 客户端的邮件服务。支持发送（自动追加个人签名 / 品牌介绍页链接）、收取、读取邮件正文、连接测试。

兼容 **WorkBuddy**、Claude Desktop、Cursor 等所有支持 MCP 协议的工具。通过云端部署，可以让 WorkBuddy 电脑端、移动端共用同一个邮箱入口，随时随地用自然语言处理自己的邮件事务。

## 特性

- ✉️ `send_email`：发送邮件，自动追加"由 xx 通过 xx 自动发送"的个人签名（含介绍页链接，可作为个人 IP 入口）
- 📥 `get_recent_emails`：获取最近 N 天邮件列表（主题 / 发件人 / 时间）
- 📖 `get_email_content`：按 UID 读取邮件完整正文与附件信息
- 🔌 `test_email_connection`：一键测试 SMTP / IMAP 连接
- 🚀 两种传输方式：stdio（本地调试） / SSE（云端远程部署）
- 🔐 端点 Bearer Token 鉴权，所有凭据走环境变量，绝不硬编码

## 架构

```
┌──────────────┐   HTTPS + Bearer   ┌──────────────────┐   SMTP/IMAP   ┌──────────────┐
│ WorkBuddy    │ ─────────────────▶ │ ai-mail-mcp      │ ────────────▶ │ 你的域名邮箱   │
│ 桌面端 / 移动端 │                   │ (云端 MCP Server) │               │ you@your.com │
└──────────────┘                   └──────────────────┘               └──────────────┘
```

云端部署是关键：一个 HTTPS 端点，桌面端、移动端都能连，本机无需开机。

## 快速开始

### 1. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入你的邮箱账号、授权码、SMTP/IMAP 地址、Bearer Token
```

### 2A. 本地调试（stdio）

```bash
npm install
MCP_TRANSPORT=stdio node server.js
```

### 2B. 云端部署（SSE，推荐）

需要一台有公网 IP 的服务器 + 一个域名（HTTPS）。

```bash
cp .env.example .env   # 在服务器上填写真实配置
docker compose up -d
```

再用 nginx 反向代理 + acme.sh/certbot 签 HTTPS 证书（`docker-compose.yml` 内有注释示例），
得到形如 `https://mcp.your-domain.com/mail-mcp/sse` 的端点。

### 3. 接入 WorkBuddy（自定义连接器）

编辑 `~/.workbuddy/mcp.json`：

```json
{
  "mcpServers": {
    "ai-mail-mcp": {
      "type": "sse",
      "url": "https://mcp.your-domain.com/mail-mcp/sse",
      "headers": {
        "Authorization": "Bearer 你的随机Token"
      }
    }
  }
}
```

在 WorkBuddy 连接器管理页对该连接器点击 Trust / 启用并重启会话，即可在对话中：

- "给 xx 发一封邮件，主题…，正文…"
- "看看我最近 3 天的邮件，总结一下哪些需要回复"
- "每天早上 9 点把昨天的邮件总结发到我的邮箱"

## 工具列表

| 工具 | 说明 | 关键参数 |
|---|---|---|
| `send_email` | 发送邮件（自动追加签名） | `to[]` `subject` `text`（必填），`cc` `bcc` `html` `attachments` 可选 |
| `get_recent_emails` | 最近邮件列表 | `limit`（默认20）`days`（默认3） |
| `get_email_content` | 读取邮件全文 | `uid`（必填） |
| `test_email_connection` | 测试 SMTP/IMAP | 无 |

## 安全提示

- `MCP_BEARER_TOKEN` 务必设置为足够随机的长字符串（`openssl rand -hex 32` 生成），并妥善保管
- `.env`、真实凭据**不要提交到任何仓库**；本文档仓库只提交 `.env.example`
- 邮箱建议使用独立账号 + 最小权限（仅收发，不开删除/管理权限）
- 自托管意味着邮件数据全程在自己服务器，不上交第三方

## License

MIT