内容
# thunderbird-mcp
一个MCP服务器，允许Claude访问Thunderbird — 读取和搜索所有连接账户（包括iCloud）的电子邮件，查找联系人，并访问统一日历。
读取路径直接与您的Thunderbird配置文件文件一起工作，不需要Thunderbird正在运行。发送电子邮件需要Thunderbird正在运行，并加载捆绑的WebExtension（参见下文）。
## 状态
- ✅ 电子邮件读取路径：列出账户/文件夹，搜索电子邮件，读取完整消息
- ✅ 联系人读取路径：列出通讯录，列出/搜索联系人
- ✅ 日历读取路径：列出日历，列出事件（需要Thunderbird关闭）
- ✅ 本地HTTP桥 + WebExtension：心跳 + 发送电子邮件
- ✅ 消息管理：移动，删除，标记已读/未读，添加/删除标签
- ✅ 联系人写入：创建/更新联系人
- ❌ 日历写入 — 阻止，没有标准的`browser.calendar` WebExtension API存在（参见`docs/DECISIONS.md` D-010）；日历仅可读
## 设置
1. 查找您的Thunderbird配置文件目录：
```bash
cat ~/.thunderbird/profiles.ini
ls ~/.thunderbird/
```
选择包含`Mail/`、`ImapMail/`、`abook.sqlite`等的配置文件目录。
2. 安装依赖项：
```bash
npm install
```
3. 将`.env.example`复制到`.env`并将`THUNDERBIRD_PROFILE`设置为您的配置文件目录：
```bash
cp .env.example .env
# edit .env
```
4. 验证它是否有效：
```bash
npm run test:tools
```
## 连接到Claude Desktop / Cowork
在`~/.config/Claude/claude_desktop_config.json`中添加一个`mcpServers`下的条目：
```json
"thunderbird": {
"command": "node",
"args": ["/absolute/path/to/thunderbird-mcp/src/index.js"],
"env": {
"THUNDERBIRD_PROFILE": "/home/<you>/.thunderbird/<profile-dir>"
}
}
```
重启Claude Desktop。然后，您应该能够询问诸如“列出我的Thunderbird账户”或“搜索我的收件箱中的发票”等问题。
## 工具
- `list_accounts` — 列出配置的Thunderbird账户
- `list_folders` — 列出账户的文件夹树
- `search_emails` — 按账户、文件夹、发件人、主题、关键词、日期范围搜索
- `read_email` — 一个消息的完整头部、文本正文和附件元数据
- `list_address_books` — 列出配置的通讯录及其同步账户
- `list_contacts` — 按姓名或电子邮件列出/搜索联系人
- `list_calendars` — 列出配置的日历
- `list_events` — 按日历/日期范围列出日历事件（需要Thunderbird关闭）
- `bridge_status` — 报告Thunderbird WebExtension是否连接
- `send_email` — 从连接的账户撰写并发送新电子邮件（需要Thunderbird运行并加载扩展；请先检查`bridge_status`）
- `list_tags` — 列出配置的消息标签/标签（键、名称、颜色）
- `move_message` — 将消息移动到另一个文件夹/账户（需要扩展）
- `delete_message` — 删除消息，默认为放入回收站（需要扩展）
- `set_message_read` — 标记消息为已读或未读（需要扩展）
- `update_message_tags` — 在消息上添加/删除标签（需要扩展）
- `create_contact` — 在通讯录中创建联系人（需要扩展）
- `update_contact` — 更新现有联系人的字段（需要扩展）
参见`docs/ARCHITECTURE.md`了解电子邮件解析、消息寻址和WebExtension桥的工作原理，以及`docs/BRIEF.md`了解项目范围和路线图。
## WebExtension
`extension/`是一个Manifest V2 Thunderbird WebExtension，与本地桥接连接。要加载它：
1. 在Thunderbird中：设置 → 通用 → “附加组件和主题” → 齿轮图标 → “调试附加组件” → “加载临时附加组件” → 选择`extension/manifest.json`。
2. 运行`npm start`，调用`bridge_status`工具（或`curl http://127.0.0.1:8084/health`）— `extensionConnected`应在约30秒内变为`true`。
连接后，`send_email`、消息管理工具（`move_message`、`delete_message`、`set_message_read`、`update_message_tags`）和联系人写入工具（`create_contact`、`update_contact`）可用。日历写入操作未实现 — 参见`docs/DECISIONS.md` D-010。
## 约束
- 本地仅限 — 无网络暴露，无Cloudflare隧道。桥梁绑定到`127.0.0.1:8084`（可通过`BRIDGE_PORT`覆盖），并且绝不能被隧道化。
- `sqlite3`，而非`better-sqlite3`（Node v24兼容性所需）
- `THUNDERBIRD_PROFILE`必须通过环境变量设置 — 绝不能硬编码
## 已知限制
- **日历仅可读。** `create_event`/`update_event`/`delete_event`未实现 — Thunderbird没有标准的`browser.calendar` WebExtension API（参见`docs/DECISIONS.md` D-010）。**适用于Google支持的日历的解决方法**：如果您的Thunderbird日历是从Google账户通过CalDAV同步的，请使用Claude单独的Google Calendar连接器直接创建/更新/删除该账户上的事件 — 更改同步回Thunderbird并通过`list_events`显示。但是，这对iCloud支持的日历没有帮助。
- **`list_events`需要Thunderbird关闭** — 日历缓存数据库（`calendar-data/local.sqlite`）在Thunderbird运行时被独占锁定（D-006）。
- **不支持回复/回复所有** — 仅支持撰写和发送（D-008）。
- `search_emails`/`read_email`的消息ID基于mbox字节偏移量，在Thunderbird压缩文件夹（例如清空回收站）后可能会过时 — 如果工具报告“消息未找到”，请重新运行`search_emails`。
## 故障排除
- **`bridge_status`报告`extensionConnected: false`**：确保Thunderbird正在运行并且扩展已加载（参见上面的“WebExtension”），并且没有其他thunderbird-mcp进程绑定到相同的`BRIDGE_PORT`（一次只能有一个进程占用该端口；`npm run test:tools`出于此原因使用单独的端口）。
- **`list_events`/`list_contacts`报告“锁定”错误`**：`list_events`需要Thunderbird关闭（D-006）。`list_contacts`可能会在Thunderbird主动CardDAV同步通讯录时暂时出现此问题 — 稍等片刻然后重试（D-008）。
- **管理工具（`move_message`等）报告“消息未找到”**：`id`已过期 — 重新运行`search_emails`以获取新的`id`。
- **发送/管理/联系人写入工具超时**：扩展程序在30秒内未响应。请在浏览器控制台（设置 → 通用 → “附加组件和主题” → 齿轮图标 → “调试附加组件” → “检查”）中检查`background.js`中的错误。
