内容
# Iobox
[](https://pypi.org/project/iobox/)
[](https://pypi.org/project/iobox/)
[](https://github.com/timainge/iobox/actions/workflows/ci.yml)
[](LICENSE)
[](https://timainge.github.io/iobox/)
你的电子邮件、日历和文件现在都集中在一个地方。你的电子邮件在一个地方，日历在另一个地方，文件又在另一个地方。
**Iobox 将它们放在同一个盒子里。** 一个工作空间可以同时跨越多个账户和服务查询——电子邮件、日历事件和文件——并返回干净的 Markdown 格式。你可以从命令行界面（CLI）使用它，也可以将其通过 MCP 连接到 Claude Desktop，这样你的 AI 助手可以直接搜索你的收件箱。
> **状态（v0.5.0）：** Google 服务提供商（Gmail、日历、Drive）已经经过实时测试。Microsoft 365 服务提供商（Outlook、OneDrive）已经完全实现，但尚未针对真实租户进行测试——预计会有一些问题，请提出问题。
## 为什么
电子邮件收件箱、日历和文件驱动器都充满了有价值的内容，但它们被隔离起来。Iobox 将它们统一在一个接口下：一次跨越所有三种资源类型进行搜索，将结果保存为结构化的 Markdown 文件，并通过 MCP 服务器将所有内容暴露给 AI 助手。
## 已实现功能
Iobox 涵盖了 Google 和 Microsoft 365 的电子邮件、日历和文件的完整读写表面。
### 服务提供商
| 服务提供商 | 类型 | 读取 | 写入 |
|---|---|---|---|
| `GmailProvider` | 电子邮件 | 搜索、列出、获取、附件 | 发送、转发、草稿、标签、删除、同步 |
| `OutlookProvider` | 电子邮件 | 搜索、列出、获取、附件 | 发送、转发、草稿、标签、删除 |
| `GoogleCalendarProvider` | 日历 | 列出、获取 | 创建、更新、删除、RSVP |
| `OutlookCalendarProvider` | 日历 | 列出、获取 | 创建、更新、删除、RSVP |
| `GoogleDriveProvider` | 文件 | 搜索、列出、获取、下载 | 上传、删除、创建目录 |
| `OneDriveProvider` | 文件 | 搜索、列出、获取、下载 | 上传、删除、创建目录 |
### 工作空间层
- **命名工作空间** — 在 `~/.iobox/workspaces/NAME.toml` 文件中配置多个账户
- **扇出查询** — 一个搜索命令同时查询所有已注册的服务提供商；部分失败将被记录并跳过
- **`iobox space`** 命令组 — 创建、添加、列出、状态、使用、登录、注销
### 处理层
- **Markdown 转换** — 任何电子邮件、事件或文件资源都导出为带有 YAML 前置信息的结构化 Markdown
- **文件管理器** — 将资源保存到磁盘，重复数据删除和附件处理
- **AI 摘要** — Claude 驱动的摘要（`pip install 'iobox[ai]'`）
- **语义搜索** — 嵌入后端（OpenAI、Voyage、本地）+ sqlite-vec 索引（`pip install 'iobox[semantic]'`）
### 访问模式
- **只读** — 仅搜索和检索；不写入
- **标准** — 添加草稿创建、标签、日历和文件写入
- **危险** — 添加发送、转发和删除
### MCP 服务器
通过 FastMCP 将所有工作空间工具暴露给 Claude Desktop 和其他 MCP 客户端。
## 安装
```bash
pip install iobox
```
### 可选附加组件
```bash
pip install 'iobox[outlook]' # Microsoft 365 / Outlook 支持
pip install 'iobox[mcp]' # 用于 Claude Desktop 的 MCP 服务器
pip install 'iobox[ai]' # 通过 Claude 进行 AI 摘要
pip install 'iobox[semantic]' # 语义搜索（OpenAI 嵌入 + sqlite-vec）
```
### 从源代码安装
```bash
git clone https://github.com/timainge/iobox.git
cd iobox
uv sync
```
## 快速入门
### Gmail 设置
1. 创建一个 Google Cloud 项目，并启用 **Gmail API**、**Google Calendar API** 和 **Google Drive API**。
2. 下载 OAuth 凭证（桌面应用类型）作为项目根目录下的 `credentials.json`。
3. 运行你的第一个命令 — 一个浏览器窗口将打开以进行 OAuth 同意：
```bash
iobox search -q "from:boss@example.com" -d 7
```
### 工作空间设置（多账户）
```bash
# 创建一个工作空间
iobox space create personal
# 添加具有消息、日历和驱动器访问权限的 Gmail
iobox space add gmail you@gmail.com --messages --calendar --drive --read
# 检查状态
iobox space status
# 跨所有资源类型搜索
iobox events list --after 2026-01-01
iobox files list --query "Q4 report"
```
### Outlook / Microsoft 365 设置
```bash
pip install 'iobox[outlook]'
export OUTLOOK_CLIENT_ID=<your Azure app client ID>
export OUTLOOK_TENANT_ID=<your tenant ID or "common">
iobox space add outlook you@company.com --messages --calendar --read
```
### MCP 服务器（Claude Desktop）
```bash
pip install 'iobox[mcp]'
```
添加到您的 Claude Desktop 配置（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"iobox": {
"command": "iobox-mcp",
"env": {
"IOBOX_MODE": "readonly"
}
}
}
}
```
## CLI 参考
### 电子邮件命令
```bash
# 搜索
iobox search -q "from:newsletter@example.com" -d 3
# 保存电子邮件
iobox save -q "label:important" --max 50 -d 14 -o ./emails
# 发送
iobox send --to recipient@example.com --subject "Hello" --body "Message"
# 转发
iobox forward --message-id MESSAGE_ID --to recipient@example.com
# 草稿
iobox draft-create --to recipient@example.com -s "Subject" -b "Body"
iobox draft-list --max 10
iobox draft-send --draft-id DRAFT_ID
iobox draft-delete --draft-id DRAFT_ID
# 标签 / 删除
iobox label --message-id MSG_ID --star --mark-read
iobox trash --message-id MSG_ID
```
### 日历命令
```bash
# 列出事件
iobox events list --after 2026-01-01 --before 2026-04-01
# 获取单个事件
iobox events get EVENT_ID
# 保存事件为 Markdown
iobox events save EVENT_ID -o ./events
# 创建事件（需要 --mode standard）
iobox events create --title "Team meeting" --start "2026-04-01T10:00:00" \
--end "2026-04-01T11:00:00" --attendee alice@company.com
# RSVP（需要 --mode standard）
iobox events rsvp EVENT_ID --response accepted
# 删除（需要 --mode standard）
iobox events delete EVENT_ID
```
### 文件命令
```bash
# 列出文件
iobox files list --query "Q4 report"
# 获取文件元数据
iobox files get FILE_ID
# 保存文件信息为 Markdown
iobox files save FILE_ID -o ./files
# 上传（需要 --mode standard）
iobox files upload ./report.pdf --name "Q4 Report.pdf"
# 删除到回收站（需要 --mode standard）
iobox files delete FILE_ID
# 创建文件夹
iobox files mkdir "Q4 Reports"
```
### 工作空间命令
```bash
# 创建和管理工作空间
iobox space create NAME
iobox space list
iobox space use NAME
iobox space status
# 管理服务会话
iobox space add gmail you@gmail.com --messages --calendar --drive --read
iobox space add outlook you@company.com --messages --calendar
iobox space login 1 # 通过槽号重新认证
iobox space logout 1 # 撤销令牌，保持配置
iobox space remove 1 # 完全删除槽
```
### 访问模式
```bash
# 只读 — 仅搜索和检索
iobox --mode readonly search -q "test"
# 标准 — 添加草稿、标签、日历/文件写入
iobox --mode standard events create --title "Meeting" ...
# 危险 — 添加发送、转发、删除
iobox --mode dangerous send --to recipient@example.com --subject "Hi" --body "Hello"
```
通过 `--mode` 标志或 `IOBOX_MODE` 环境变量设置。
## 输出格式
保存为带有 YAML 前置信息的 Markdown 的电子邮件：
```markdown
---
date: Mon, 23 Mar 2026 10:00:00 +1100
from: sender@example.com
labels: [INBOX]
message_id: 123456789abcdef
saved_date: 2026-03-24T21:30:00.123456
subject: Your Newsletter Subject
to: recipient@example.com
---
# Your Newsletter Subject
[Markdown 电子邮件内容]
```
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `IOBOX_PROVIDER` | `gmail` | 活动提供商：`gmail` 或 `outlook` |
| `IOBOX_MODE` | `standard` | 访问模式：`readonly`、`standard`、`dangerous` |
| `IOBOX_ACCOUNT` | `default` | 用于令牌存储的账户配置文件 |
| `CREDENTIALS_DIR` | `.` | 凭证和令牌文件的目录 |
| `GOOGLE_APPLICATION_CREDENTIALS` | `credentials.json` | Google OAuth 凭证路径 |
| `OUTLOOK_CLIENT_ID` | — | Azure 应用客户端 ID（Outlook 需要） |
| `OUTLOOK_TENANT_ID` | `common` | Azure 租户 ID |
## 开发
```bash
uv sync
make check # 校验 + 类型检查 + 测试
make test # 仅测试
```
## 文档
完整文档：[timainge.github.io/iobox](https://timainge.github.io/iobox)
## 许可证
MIT — 参见 [LICENSE](LICENSE) 获取详细信息。
