内容
# 紫罗兰邮箱 MCP 服务器
> 紫罗兰邮箱的模型上下文协议服务器。您的 AI 代理可以发送、接收、搜索和跟踪电子邮件。
## 什么是紫罗兰邮箱 MCP 服务器？
**紫罗兰邮箱 MCP 服务器** 通过 [模型上下文协议](https://modelcontextprotocol.io/) 将您的 AI 代理（如 Claude、Cursor 等）连接到您的紫罗兰邮箱账户。
您的代理可以：
- **发送和调度电子邮件**，来自您自己的域名
- **读取和搜索收件消息**，具有全文搜索功能
- **跟踪已发送邮件的投递状态**
- **设置新域名**，并复制粘贴 DNS 记录
- **引用** 您的域名、邮箱和别名
## 安装
需要 Node.js 18+。
下面的客户端配置使用 `npx -y purpletoadmail-mcp` 运行服务器。
## 快速入门
### 1. 获取 API 密钥
登录 [app.purpletoadmail.com](https://app.purpletoadmail.com) → 设置 → API 密钥 → **创建密钥**。
复制密钥（以 `pt_live_` 或 `pt_test_` 开头）。它只显示 **一次**。
### 2. 配置
**选项 A — 环境变量：**
```bash
export PURPLETOAD_API_KEY="pt_live_your_key_here"
export PURPLETOAD_DEFAULT_FROM="agent@yourdomain.com"
```
**选项 B — 配置文件：**
```bash
mkdir -p ~/.purpletoad
cat > ~/.purpletoad/config.json <<EOF
{
"apiKey": "pt_live_your_key_here",
"defaultFrom": "agent@yourdomain.com"
}
EOF
```
### 3. 连接到您的 AI 客户端
下面的示例使用 `npx -y purpletoadmail-mcp`。
#### Claude 桌面版
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"purpletoad": {
"command": "npx",
"args": ["-y", "purpletoadmail-mcp"],
"env": {
"PURPLETOAD_API_KEY": "pt_live_your_key_here",
"PURPLETOAD_DEFAULT_FROM": "agent@yourdomain.com"
}
}
}
}
```
#### Cursor / Windsurf
添加到您的 MCP 设置：
```json
{
"mcpServers": {
"purpletoad": {
"command": "npx",
"args": ["-y", "purpletoadmail-mcp"],
"env": {
"PURPLETOAD_API_KEY": "pt_live_your_key_here"
}
}
}
}
```
#### Kimi 代码 CLI
Kimi 代码通过 `~/.kimi-code/mcp.json`（或旧版本中的 `~/.kimi/mcp.json`）支持 MCP：
```bash
mkdir -p ~/.kimi-code
cat > ~/.kimi-code/mcp.json <<'EOF'
{
"mcpServers": {
"purpletoad": {
"command": "npx",
"args": ["-y", "purpletoadmail-mcp"],
"env": {
"PURPLETOAD_API_KEY": "pt_live_your_key_here",
"PURPLETOAD_DEFAULT_FROM": "agent@yourdomain.com"
}
}
}
}
EOF
```
然后在新会话中运行 `kimi`，或在 Kimi 代码中使用 `/mcp-config` 验证连接。
#### SSE（远程/自托管）
```bash
PURPLETOAD_TRANSPORT=sse PURPLETOAD_PORT=3001 node dist/index.js
```
然后使用 `http://localhost:3001/sse` 配置您的客户端。
> **安全注意：** SSE 端点需要初始 `/sse` 请求中的 `Authorization: Bearer <PURPLETOAD_API_KEY>`。如果没有有效的令牌，则连接将被拒绝，返回 HTTP 401。
### 后端要求
不需要额外的后端工作。MCP 服务器与标准的紫罗兰邮箱 API（默认为 `https://api.purpletoadmail.com`，可通过 `PURPLETOAD_BASE_URL` 重写）通信。只需确保您的 API 密钥具有所需的范围（`send`、`read`、`manage`）。
## 工具参考
服务器暴露 **23 个工具**。
### 电子邮件操作
| 工具 | 描述 |
|------|-------------|
| `send_email` | 从紫罗兰邮箱的邮箱发送电子邮件 |
| `reply_to_message` | 回复收到的电子邮件，保留线程 |
| `schedule_email` | 调度电子邮件以备将来投递 |
| `cancel_scheduled_email` | 在电子邮件投递之前取消调度 |
| `list_messages` | 列出收到的电子邮件，并带有过滤器（未读、从、线程） |
| `get_message` | 获取完整的消息正文和附件 |
| `search_messages` | 跨所有收件电子邮件进行全文搜索 |
| `mark_read` | 将一个或多个消息标记为已读 |
| `archive_message` | 存档消息以保持收件箱干净 |
| `list_outbound_messages` | 列出已发送的电子邮件及其投递状态 |
| `get_outbound_message` | 跟踪单个电子邮件的投递历史 |
| `get_mailbox_status` | 邮箱的未读计数和配额使用情况 |
| `get_account` | 账户资料、计划和使用情况统计 |
### 基础设施参考
| 工具 | 描述 |
|------|-------------|
| `list_domains` | 列出所有具有 DNS 健康和邮箱计数的域名 |
| `get_domain` | 获取详细的域名信息，包括 DNS 记录 |
| `list_mailboxes` | 列出所有具有配额使用情况的邮箱 |
| `get_mailbox` | 获取邮箱详细信息（配额、最后登录、替代电子邮件） |
| `list_aliases` | 列出所有具有源和目标的电子邮件别名 |
| `get_alias` | 获取电子邮件别名详细信息 |
### 域名和邮箱设置
| 工具 | 描述 |
|------|-------------|
| `create_domain` | 添加新域名并接收复制粘贴的 DNS 记录。需要 `manage` 范围。 |
| `create_mailbox` | 在已验证的域名下创建邮箱。密码仅显示一次 — 立即更改。需要 `manage` 范围。 |
| `update_mailbox_password` | 更新邮箱密码。请谨慎使用。需要 `manage` 范围。 |
| `create_alias` | 创建转发到目标邮箱的电子邮件别名。需要 `manage` 范围。 |
### Webhooks
| 工具 | 描述 |
|------|-------------|
| `set_webhook` | 配置用于推送投递入站电子邮件事件的 webhook 端点。需要 `manage` 范围。 |
## 示例工作流程
### "发送欢迎电子邮件"
```
用户：从 hello@mycompany.com 向 john@example.com 发送欢迎电子邮件
代理：send_email(
from="hello@mycompany.com",
to=["john@example.com"],
subject="欢迎来到 MyCompany！",
text="感谢您的注册..."
)
```
### "检查我的未读电子邮件"
```
用户：我在 support@mycompany.com 有未读电子邮件吗？
代理：list_messages(mailbox="support@mycompany.com", unread_only=true)
代理：get_account()
```
### "查找上周的发票"
```
用户：查找我上周收到的来自 Acme Corp 的发票邮件
代理：search_messages(query="invoice Acme")
代理：get_message(message_id="...")
```
### "设置新域名"
```
用户：在紫罗兰邮箱中添加 mycompany.com
代理：create_domain(domain="mycompany.com")
```
代理返回格式化后的 DNS 表：
```
| 类型 | 主机（名称） | 值 / 指向 | 优先级 | TTL |
|-------|--------------------|----------------------------------------------|----------|------|
| MX | @ | mx.purpletoadmail.com | 10 | 3600 |
| TXT | @ | v=spf1 include:mx.purpletoadmail.com ~all | — | 3600 |
| TXT | pt2024._domainkey | v=DKIM1; k=rsa; p=MIGfMA... | — | 3600 |
| TXT | _dmarc | v=DMARC1; p=quarantine; ... | — | 3600 |
```
将这些复制到您的 DNS 提供商（Cloudflare、Namecheap、GoDaddy 等）。域名将在几分钟内自动验证。
### "创建邮箱"
```
用户：创建新的邮箱 support@mycompany.com
代理：create_mailbox(
domain_id="uuid",
local_part="support",
display_name="支持团队",
quota_mb=512
)
```
代理返回新的邮箱密码。**复制并立即更改它** — 它只显示一次。
### "创建支持别名"
```
用户：设置一个支持别名，转发给 alice 和 bob
代理：create_alias(
domain_id="uuid",
source="support",
targets=["alice@mycompany.com", "bob@mycompany.com"]
)
```
### "跟踪新闻稿是否已投递"
```
用户：昨天的新闻稿是否已投递？
代理：list_outbound_messages(
date_from="2026-06-01",
status="delivered"
)
代理：get_outbound_message(message_id="...")
```
### "调度跟进"
```
用户：为下周一上午 9 点调度跟进电子邮件
代理：schedule_email(
from="sales@mycompany.com",
to=["prospect@example.com"],
subject="跟进",
text="只是确认...",
send_at="2026-06-08T09:00:00Z"
)
```
## 配置参考
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `PURPLETOAD_API_KEY` | **是** | — | 您的 API 密钥（`pt_live_*` 或 `pt_test_*`） |
| `PURPLETOAD_DEFAULT_FROM` | 否 | — | 如果省略 `from`，则使用默认发件人地址 |
| `PURPLETOAD_BASE_URL` | 否 | `https://api.purpletoadmail.com` | API 基址 |
| `PURPLETOAD_TIMEOUT` | 否 | `30` | 请求超时（秒） |
| `PURPLETOAD_TRANSPORT` | 否 | `stdio` | `stdio` 或 `sse` |
| `PURPLETOAD_PORT` | 否 | `3001` | SSE 传输端口 |
## 错误处理
所有工具返回结构化的 JSON，如果出错则 `success: false`：
```json
{
"success": false,
"error": "RATE_LIMIT_EXCEEDED",
"message": "每日电子邮件限制已达到。",
"suggestion": "等待至明日或在 app.purpletoadmail.com 升级您的计划。"
}
```
常见错误代码：
| 代码 | 含义 | 建议 |
|------|---------|------------|
| `INVALID_FROM` | 发件人不是有效邮箱 | 使用 `list_mailboxes` 查找有效地址 |
| `DOMAIN_NOT_VERIFIED` | 缺少 DNS 记录 | 使用 `get_domain` 查看所需记录 |
| `RATE_LIMIT_EXCEEDED` | 计划限制已达到 | 等待或在 app.purpletoadmail.com 升级 |
| `INSUFFICIENT_SCOPE` | API 密钥缺乏权限 | 在仪表盘中创建具有所需范围的密钥 |
| `TIMEOUT` | 请求超时 | 重试或增加 `PURPLETOAD_TIMEOUT` |
## 速率限制
速率限制、配额和附件大小因计划而异。请在您的账户仪表盘中查看当前的限制。
`send_email` 和 `schedule_email` 工具在响应中返回剩余配额。
## 支持
- **仪表盘：** [app.purpletoadmail.com](https://app.purpletoadmail.com)
- **支持：** hello@purpletoadmail.com
## 许可证
MIT © 紫罗兰邮箱
