macbird (Richard Hajek)

\[！警告\] 此服务器提供对您所有配置的Thunderbird帐户的直接访问。仅与值得信赖的AI助手一起使用。

雷鸟MCP服务器

一种模型上下文协议（MCP）服务器，通过与Thunderbird扩展的WebSocket连接，为AI助手提供对Thunderbirt电子邮件功能的访问。

建筑

该项目由三个部分组成：

1. MCP服务器 -在stdio上运行，并为AI助手提供MCP工具
2. WebSocket服务器 -连接到Thunderbird扩展 ws://localhost:37842/ws
3. 雷鸟扩展 -与Thunderbird API接口的WebExtension

AI Assistant (Claude, etc.)
    ↕ stdio (MCP protocol)
MCP Server (server.ts)
    ↕ WebSocket (localhost:37842)
Thunderbird Extension
    ↕ Thunderbird WebExtension APIs
Thunderbird Email Client

快速开始

此软件尚未在任何软件包存储库中，请下载并手动使用。

1.安装服务器依赖关系

git clone https://github.com/richard-hajek/macbird.git
cd macbird
cd server
bun install

2.加载Thunderbird扩展

1. 打开雷鸟
2. 首选 工具→ 开发者工具→ 调试附加组件
3. 点击 “加载临时附加组件”
4. 导航至 addon/ 目录并选择 manifest.json

该扩展将自动连接到MCP服务器。

3.配置MCP客户端

添加到MCP客户端配置中：

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "thunderbird": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/thunderbird-mcp/server/server.ts"]
    }
  }
}

其他MCP客户端:

bun run /path/to/server/server.ts

4.开始使用！

配置后，您的AI助手可以通过以下工具访问您的电子邮件。

可用工具

list_accounts

列出在Thunderbird中配置的所有电子邮件帐户。

list_accounts()
// Returns: { accounts: [...], count: N }

list_folders

列出特定帐户或所有帐户的所有文件夹。

参数：

• accountId （可选）：按帐户ID筛选

list_folders()
list_folders({ accountId: "account1" })

list_unread_emails

列出所有帐户或特定文件夹中的所有未读电子邮件。

参数：

• accountId （可选）：按帐户ID筛选
• folderId （可选）：按文件夹ID筛选
• limit （可选）：最大电子邮件数（默认值：50）
• includeSpam （可选）：包括垃圾邮件/垃圾/时事通讯文件夹（默认值：false）
• afterDate （可选）：仅限此日期之后的电子邮件（ISO 8601格式）

list_unread_emails()
list_unread_emails({ accountId: "account1", limit: 20 })
list_unread_emails({ afterDate: "2024-01-01T00:00:00Z" })

search_emails

使用各种条件搜索电子邮件。

参数：

• query （可选）：主题/正文/发件人/收件人的搜索查询
• from （可选）：按发件人筛选
• to （可选）：按收件人筛选
• subject （可选）：按主题筛选
• unread （可选）：按未读状态筛选
• flagged （可选）：按标记状态筛选
• limit （可选）：最大结果（默认值：50）

search_emails({ from: "john@example.com" })
search_emails({ query: "invoice", unread: true })

read_email_raw

阅读特定电子邮件的原始完整内容，包括所有标题和原始格式。

参数：

• messageId （必填）：要读取的消息ID
• markAsRead （可选）：标记为已读（默认值：false）

read_email_raw({ messageId: 12345, markAsRead: true })

read_email

阅读一封特定的电子邮件，其中重要的标题和正文已转换为markdown格式。

参数：

• messageId （必填）：要读取的消息ID
• markAsRead （可选）：标记为已读（默认值：false）

read_email({ messageId: 12345, markAsRead: true })
// Returns clean markdown-formatted email body

send_email

发送一封新电子邮件。

参数：

• to （必填）：收件人电子邮件地址数组
• subject （必填）：电子邮件主题
• body （必填）：电子邮件正文
• cc （可选）：CC地址数组
• bcc （可选）：BCC地址数组
• isHtml （可选）：正文是否为HTML（默认值：false）
• accountId （可选）：要发送的帐户

send_email({
  to: ["recipient@example.com"],
  subject: "Hello from MCP",
  body: "This email was sent via the Thunderbird MCP server!",
  cc: ["cc@example.com"]
})

read_email_attachments

将特定电子邮件中的所有附件下载到文件夹中。

参数：

• messageId （必填）：包含附件的邮件ID
• downloadPath （必填）：应保存文件的本地路径

read_email_attachments({
  messageId: 12345,
  downloadPath: "/home/user/Downloads"
})

download_attachment

下载一个特定的附件。

参数：

• messageId （必填）：包含附件的邮件ID
• partName （必填）：附件零件名称/标识符
• downloadPath （必填）：应保存文件的本地路径

download_attachment({
  messageId: 12345,
  partName: "1.2",
  downloadPath: "/home/user/Downloads/document.pdf"
})

用法示例

配置后，您可以通过AI助手使用这些工具：

You: "Can you check my unread emails?"
AI: *uses list_unread_emails tool*
AI: "You have 5 unread emails. The most recent is from..."

You: "Search for emails from john@example.com about the project"
AI: *uses search_emails tool*
AI: "I found 3 emails from john@example.com..."

You: "Read that email and convert it to markdown"
AI: *uses read_email tool*
AI: "Here's the email in markdown format: ..."

You: "Send a reply"
AI: *uses send_email tool*
AI: "I've sent the reply."

发展

项目结构

thunderbird-mcp/
├── addon/                      # Thunderbird WebExtension
│   ├── background.js           # Main extension logic (182 lines)
│   ├── background_handlers.js  # Command handlers (388 lines)
│   └── manifest.json           # Extension manifest
├── server/                     # MCP Server
│   └── server.ts               # Combined MCP + WebSocket server
├── DEVELOPMENT.md              # Development guide
└── README.md                   # This file

开发脚本

服务器：

cd server
bun run lint         # Check for linting errors
bun run lint:fix     # Auto-fix linting errors  
bun run typecheck    # Type-check TypeScript
bun run dev          # Run server

插件：

cd addon
bun install          # Install dev dependencies
bun run lint         # Check for linting errors
bun run lint:fix     # Auto-fix linting errors

直接运行服务器

cd server
bun run server.ts

这从两个方面开始：

• stdio上的MCP服务器
• WebSocket服务器已打开 ws://localhost:37842/ws

检查连接状态

访问 http://localhost:37842/status 查看已连接的Thunderbird客户端。

调试

服务器记录到stderr（在MCP客户端日志中可见）。插件登录到Thunderbird控制台（Ctrl+Shift+J）。

特性

• ✅ HTML到Markdown的转换 -使用Turndown将电子邮件转换为干净的降价
• ✅ 单客户端模型 -为了简单起见，新连接摒弃了旧连接
• ✅ 自动重新连接 -如果断开连接，扩展将每5秒自动重新连接一次
• ✅ 垃圾邮件过滤 -默认情况下自动排除垃圾邮件/垃圾邮件/时事通讯文件夹
• ✅ 日期筛选 -按日期过滤电子邮件
• ✅ 类型安全 -用TypeScript编写的服务器，具有严格的类型检查
• ✅ 短绒的 -服务器和插件都配置了ESLint
• ✅ 模块化处理器 -命令处理逻辑的清晰分离

故障排除

“未连接Thunderbird客户端”

• 确保Thunderbird扩展已加载
• 检查Thunderbird是否正在运行
• 在Thunderbird控制台中查找连接消息（Ctrl+Shift+J）

WebSocket连接失败

• 分机将每5秒自动重新连接一次
• 检查端口37842是否未使用： lsof -i :37842
• 在Thunderbird控制台中查找CSP（内容安全策略）错误

MCP工具不工作

• 确保服务器由MCP客户端启动（检查日志）
• 验证MCP客户端配置中的命令路径是否正确
• 检查一下 bun 已安装并位于您的PATH中

搜索超时

• 搜索在扩展中有25秒的超时
• 请尝试对您的搜索查询更加具体
• 使用 list_unread_emails 而是用于更简单的查询

端口配置

服务器使用端口 37842 以避免与通用开发端口（3000、8080等）发生冲突。您可以在以下位置更改此设置：

• server/server.ts -第43行
• addon/background.js -7号线
• addon/manifest.json -第83行

许可证

麻省理工学院