内容
# MailMavenMCP
一款遵循 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 的服务器，允许 Claude 读取、搜索和管理您在 [MailMaven](https://smallcubed.com/) 中的电子邮件——Smallcubed 的 macOS 邮件客户端。
该服务器通过 AppleScript 驱动 MailMaven，因此它与您在应用程序中设置的现有帐户和邮箱完全按照相同的方式工作。无需额外的 IMAP 凭证、API 密钥或云同步。
> **仅限 macOS。** MailMaven 是一款 macOS 应用程序，该服务器通过 AppleScript (`osascript`) 控制它。它不能在 Windows 或 Linux 上运行。
---
## Claude 可以执行的操作
连接后，Claude 获得了许多与 MailMaven 合作的工具：
**帐户和邮箱**
- `获取应用信息`，`检查新邮件`
- `列出帐户`，`列出邮箱`，`获取统一邮箱`
**阅读和搜索邮件**
- `搜索消息` — 按主题、发件人、收件人、邮件内容、关键词、项目、已读/标记/重要性状态、附件、日期范围、邮箱或帐户进行筛选
- `获取消息`，`获取最近的消息`，`获取选定的消息`
**组织消息**
- `标记为已读`，`设置标记`，`设置重要性`，`设置垃圾邮件状态`
- `设置项目`，`设置备注`，`设置审核日期`，`设置替代主题`
- `添加关键词`，`删除关键词`，`清除所有标签`
- `移动消息`，`删除消息`
**撰写邮件**
- `撰写消息`，`转发消息`
- `列出签名`，`列出模板`
**归档**
- `导出并归档到 EagleFiler`
向 Claude 提问，如 *"查找本月来自我会计师的未读邮件"*， *"将来自我老板的邮件标记为高优先级"*，或 *"使用我的工作签名草拟回复"*，它将直接调用这些工具来操作您正在运行的 MailMaven 副本。
---
## 要求
- 已安装 MailMaven 并配置了至少一个帐户的 macOS
- **Python 3.10+**
- `mcp` Python 包（提供 `mcp.server.fastmcp.FastMCP`）
- Claude Desktop 或 Claude Code
---
## 1. 安装
克隆仓库并安装一个依赖项：
```bash
git clone https://github.com/Smallcubed/MailMavenMCP.git
cd MailMavenMCP
python3 -m venv .venv
source .venv/bin/activate
pip install mcp
```
记下 `MavenMCP.py` 的完整路径 — 您在下面的配置步骤中需要它。您可以使用以下命令获取它：
```bash
pwd # 从 MailMavenMCP 文件夹内部
```
## 2. 连接到 Claude
### Claude Desktop
如果您正在使用 Claude Desktop，请在 Claude Desktop 中打开 **设置 → 开发者 → 编辑配置** （或直接打开文件）：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
在 `mcpServers` 下添加一个 `mailmaven` 条目，使用您的虚拟环境的 Python 和 `MavenMCP.py` 的 **完整路径** ： （如果没有 `mcpServers` 键，则需要添加它）
```json
...
"mcpServers": {
"mailmaven": {
"command": "/绝对路径/到/MailMavenMCP/.venv/bin/python3",
"args": ["/绝对路径/到/MailMavenMCP/MavenMCP.py"]
}
}
...
```
确保配置文件是格式良好的 json 并保存文件，然后完全重启 Claude Desktop（从菜单栏退出，不要只是关闭窗口）。
### Claude Code
如果您正在使用 Claude Code，请在终端中输入以下命令：
```bash
claude mcp add mailmaven -- /绝对路径/到/MailMavenMCP/.venv/bin/python3 /绝对路径/到/MailMavenMCP/MavenMCP.py
```
之后运行 `claude mcp list` 以确认它显示为已连接。
## 3. 授予自动化权限
服务器通过 AppleScript 调用 MailMaven，因此 macOS 需要允许启动它的进程（Claude Desktop、终端或 Claude Code）控制 MailMaven。
1. 打开 **MailMaven** 并保持运行 — 否则服务器无法访问它。
2. 打开 **系统设置 → 隐私和安全 → 自动化**。
3. 当 Claude 首次尝试使用 MailMaven 工具时，macOS 将提示您允许 Claude（或终端）控制“MailMaven”。单击 **允许**。
4. 如果您没有看到提示，或意外拒绝了它，请在自动化列表中找到该应用程序，并手动选中 **MailMaven** 复选框。
## 4. 验证是否有效
确保 MailMaven 已打开，然后向 Claude 提问一个简单的问题，例如：
> “列出我的 MailMaven 帐户。”
或
> “总结 MailMaven 前景中选定的第一个消息。”
如果它用 Maven 中的信息回应，则连接有效。如果 MailMaven 工具出现在 Claude 的工具列表中，但调用失败，请检查下面的故障排除部分。
---
## 故障排除
**“AppleScript 错误：... 不允许发送 Apple 事件”** （或 errno `-1743` ）
macOS 阻止了自动化权限。请重新访问上面的步骤 3 — 检查系统设置 → 隐私和安全 → 自动化，并确保启动服务器的应用程序（Claude Desktop 或终端）具有控制 MailMaven 的权限。
**工具超时或返回无**
MailMaven 必须正在运行，AppleScript 才能访问它。请打开应用程序并重试。
**“命令未找到”或服务器未在 Claude 中显示**
请仔细检查您的配置中的两个路径都是绝对路径（不是 `~` 或相对路径），并且它们指向您创建的虚拟环境（`.venv/bin/python3`）内的 Python 解释器，而不是您的系统 Python — 那是已安装 `mcp` 包的 Python。
**对 `MavenMCP.py` 的更改不生效**
请重启 Claude Desktop，或在 Claude Code 中运行 `claude mcp remove mailmaven` 并重新添加 — MCP 服务器仅在启动/重新连接时重新加载。
---
## 隐私和安全说明
- 此服务器仅与您自己的 Mac 上的 MailMaven 应用程序通信 — 它不会将您的邮件发送到其他任何地方。
- `删除消息` 会将消息移动到垃圾箱；通过这些工具不会永久删除任何内容。
- 由于 Claude 可以通过此服务器读取消息内容和发送/撰写邮件，因此请像处理其他可以访问您的收件箱的工具一样，在批准之前查看 Claude 即将发送的内容。
## License
MIT — 请参阅 [LICENSE](LICENSE)。
