inbox-to-action

inbox-to-action

已发布到 PyPI，并收录于 官方 MCP 注册表（io.github.tarunlnmiit/inbox-to-action）、 Glama（可部署版本，质量等级 A）， 以及 Smithery（MCPB 软件包）。 仓库中包含注册表清单（server.json、glama.json）。

一条命令，即可在一次 Agent 处理过程中完成收件箱分类、摘要、草拟回复并转化为任务。

安装

pip install inbox-to-action          # or: pipx install inbox-to-action
uvx inbox-to-action run --mock       # zero-install trial (uv)
pip install 'inbox-to-action[mcp]'   # + MCP server for Claude Code
docker run --rm ghcr.io/tarunlnmiit/inbox-to-action   # MCP server (stdio)

无需任何设置即可试用：inbox-to-action run --mock（内置示例收件箱）。

📖 完整文档 → docs/ — 安装 · 服务提供方 · Gmail OAuth · 多账户 · 集成 · MCP 与 Skill · 配置 · 故障排除 · 测试清单。快速版：SETUP.md。

---

为什么要做这个项目

大多数人会用四种不同的工具处理收件箱：用邮件客户端阅读邮件、用任务管理器记录待办事项、用日历安排时间，以及（越来越常见地）用 AI 摘要工具梳理长邮件往来。每条消息都要处理四遍。

inbox-to-action 将这四种工具整合为一次 Agent 处理流程。运行一条命令，即可获得统一的分类报告、保存到 Gmail 的回复草稿，以及提取出的任务——全程无需离开终端，且绝不会自动发送邮件。

🔒 仅保存草稿——绝不发送

此工具无法发送邮件。它仅请求 Gmail 的 readonly 和 compose 权限；没有 send 权限，代码库中也没有任何发送 API 调用（并由测试强制保证）。回复会保存为 Gmail 草稿，供你审核并发送。

邮件正文会传入大模型提示词，因此恶意邮件可能试图操纵自身的分类结果或草拟的回复（提示词注入）。由于每份草稿都需要人工审核，且绝不会自动发送，最坏的情况也只是生成一份你选择不发送的草稿。详见 SECURITY.md。

🌐 哪些内容会离开你的设备

inbox-to-action 会读取你的邮件。邮件内容会发送到哪里进行分类，取决于你选择的 LLM 提供商——而默认值（openrouter）是云端提供商，因此开箱即用的运行会将邮件主题和正文发送给第三方。

PROVIDER=	邮件内容发送到	密钥
ollama	不会发送到任何地方 — 完全在本地处理 🔒	无
claude / host	你现有的 Claude Code / Anthropic 会话（无需密钥）	无
openrouter （默认） · openai · nim · anthropic	第三方云端 ☁️	API 密钥

想要保护隐私？ 使用 ollama（本地）或 claude（无需密钥），这样就不会向第三方传输任何内容。--telegram / --todoist 也会将主题/任务发送到设备之外（需主动启用）。 完整说明 → PRIVACY.md。

注意：triage-report.md 和 tasks.md 会写入你的工作目录，其中包含私人邮件内容。如果你在 git 仓库中运行，请将它们添加到 .gitignore。

功能

1. 获取 Gmail 中未读邮件（默认获取最近 24 小时的邮件）。
2. 分类每封邮件：action_needed · fyi · newsletter · noise。
3. 总结长邮件串（>500 个单词），缩写成两行。
4. 提取带截止日期的任务 → 本地 tasks.md（可通过 --todoist 选择同步到 Todoist）。
5. 起草 action_needed 邮件的回复 → 保存为 Gmail 草稿。
6. 标记需要安排日历时段的邮件。

最终输出：一个 triage-report.md 文件，其中包含各类别的分区、回复草稿预览、任务摘要和日历列表。

架构 — Agent 循环

模型对每封邮件的分类结果会决定接下来调用哪些工具——整个流水线并非硬编码。CLI Agent 和 MCP 服务使用相同的工具函数。

flowchart TD
  CLI[main.py · typer] --> AGENT[agent.py · agentic loop]
  AGENT -->|model picks tools per email| T1[classify_email]
  AGENT --> T2[summarize_thread]
  AGENT --> T3[extract_tasks]
  AGENT --> T4[draft_reply → Gmail draft]
  AGENT --> T5[flag_for_calendar]
  T1 & T2 & T3 & T4 & T5 --> LLM[llm_client.py · pluggable providers]
  LLM --> P1[OpenRouter / Ollama / NIM / OpenAI<br/>OpenAI-compatible HTTP]
  LLM --> P2[Anthropic · official SDK · keyless via ant auth login]
  AGENT --> REPORT[report.py → triage-report.md]

fetch → for each email:  classify ─┬─ action_needed → extract_tasks + draft_reply + flag_calendar
                                   ├─ fyi / newsletter / noise → record only
                                   └─ (long thread) → summarize
                          → render triage-report.md

快速开始（2 分钟）

git clone https://github.com/tarunlnmiit/inbox-to-action.git && cd inbox-to-action
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[mcp]'        # installs the `inbox-to-action` command
cp .env.example .env

这会安装 inbox-to-action 控制台命令（以及供 Claude Code / Glama 使用的 python -m inbox_to_action.mcp_server 入口点）。

免费优先：零成本运行完整流程

选择任意一种无需密钥/免费的方式——都可以零成本运行完整流程：

选项 A — claude CLI（无需密钥，速度最快；使用你的 Claude Code 登录）：

PROVIDER=claude inbox-to-action run --mock     # no API key; needs `claude` on PATH

选项 B — Ollama（真正无需密钥，完全在本地运行）：

ollama serve            # in another terminal
ollama pull llama3.1
PROVIDER=ollama inbox-to-action run --mock     # uses bundled sample inbox

选项 C — OpenRouter 免费模型（注册即可获得免费密钥）：

# put OPENROUTER_API_KEY in .env (free models, $0 spend)
inbox-to-action run --mock                      # default PROVIDER=openrouter

选项 D — 在 Claude Code 中运行（无需密钥，Claude Code 即为 LLM）： 见下文。

--mock 使用捆绑的示例收件箱，让你无需进行任何 Gmail 设置即可查看完整报告。授权 Gmail 后，去掉 --mock。OpenRouter 免费模型通常有速率限制；客户端会自动轮换备用模型列表，并在退避等待后重试。

真实收件箱

# 1. Create OAuth credentials in Google Cloud Console (Desktop app),
#    download client_secret.json into the project, then:
inbox-to-action auth                 # one-time consent (read + compose only)
inbox-to-action run --since 24h --no-drafts   # safe first pass: report only, no writes
inbox-to-action run --since 24h      # triage the last day (creates Gmail drafts)
inbox-to-action run --since 3d --max 40 --todoist

• --no-drafts — 分类、总结、提取任务并生成报告，但不创建 Gmail 草稿。建议首次运行时使用。
• --max N — 限制每个账号处理的邮件数量（默认为 25），以控制成本/处理量。
• 自动化的 no-reply 发件人（安全提醒、通知）不会收到回复草稿——报告会对其进行说明。

Telegram 摘要（--telegram）

每次运行后将简明摘要推送到你的手机——包括数量、需要处理的邮件主题（及草稿就绪状态）、提取的任务，以及 Gmail 草稿箱链接。

# 1. In Telegram, message @BotFather → /newbot → copy the bot token.
# 2. Message your new bot once (say "hi"), then open:
#    https://api.telegram.org/bot<token>/getUpdates  → copy "chat":{"id": ...}.
# 3. Put both in .env:
#    TELEGRAM_BOT_TOKEN=...   TELEGRAM_CHAT_ID=...
inbox-to-action run --since 24h --telegram

默认关闭（需通过标志主动启用）。发送失败不会中断运行。 **隐私：**这会将邮件主题和提取的任务发送到 Telegram 的服务器（发送到你自己的聊天）。这仅用于通知——绝不会发送邮件。

多个账号（Gmail + Google Workspace）

在 config.json 中声明账号——生成一份合并报告，每封邮件都会标记所属账号。个人 Gmail 和 Workspace 都使用 Gmail 流程（Workspace 可能需要管理员允许 OAuth 应用）。

{
  "accounts": [
    { "id": "personal", "kind": "gmail", "label": "Personal Gmail" },
    { "id": "work",     "kind": "gmail", "label": "Workspace" }
  ]
}

inbox-to-action auth --account personal   # authorize each account once
inbox-to-action auth --account work
inbox-to-action run --since 24h           # fetches + triages across all accounts

多个个人 Gmail 账号可以共用一个 client_secret.json——每个账号都会有自己的缓存令牌（~/.config/inbox-to-action/tokens/<id>.json）。如果没有 accounts 配置块，工具会使用一个默认 Gmail 账号（向后兼容）。

在 Claude Code 中使用（无需密钥）

在 Claude Code 中运行时，Claude Code 就是大模型——无需提供方密钥。 本仓库提供两种集成方式：

MCP 服务

提供仅执行 IO 的工具（fetch_emails、save_gmail_draft、append_tasks、write_report）。 Claude Code 自行进行分类、摘要、提取和草拟，并调用这些工具。

# after `pip install -e '.[mcp]'`
claude mcp add inbox-to-action -- python -m inbox_to_action.mcp_server

这是同一个 stdio 服务，MCP 注册目录（例如 Glama）会通过随附的 Dockerfile（CMD python -m inbox_to_action.mcp_server）构建该服务。

Skill

将 skills/inbox-to-action/ 复制到 Claude Code 的 skills 目录，然后输入 /inbox-to-action。该 Skill 会指导 Claude Code 获取内容、推理、草拟并撰写报告——无需密钥。

Anthropic（通过 ant auth login 免密）

Anthropic 提供方使用官方 SDK 和零参数客户端，因此会读取你的 ant auth login OAuth 配置文件——无需设置 ANTHROPIC_API_KEY：

ant auth login
PROVIDER=anthropic inbox-to-action run --mock   # default model: claude-opus-4-8

配置

所有密钥都存放在 .env 中（已提交 .env.example）。通过 PROVIDER 切换提供方： openrouter（默认）· ollama · nim · openai · anthropic · claude · host

配置分流（按你的需求调整）

默认分类比较通用——简报和职位提醒会被视为无需操作。 可通过 config.json（复制 config.example.json）覆盖设置。分为两层：

• rules — 确定性的 field → category 覆盖规则，在大模型处理前应用 （快速、免费、精确）。采用首个匹配项。field ∈ sender | subject | body | any。
• triage_instructions — 自由格式的指导，会注入分类器提示词，以补充模型可理解的细节。

{
  "triage_instructions": "I'm job hunting in ML/AI — treat relevant job alerts as action_needed.",
  "rules": [
    { "field": "sender",  "contains": "hirist.tech", "category": "action_needed" },
    { "field": "subject", "contains": "invoice",     "category": "noise" }
  ]
}

cp config.example.json config.json   # edit to taste (config.json is gitignored)
inbox-to-action run --since 24h                 # auto-loads ./config.json
inbox-to-action run --config /path/to/other.json

无需文件即可快速覆盖：TRIAGE_INSTRUCTIONS="treat job alerts as action_needed"。

测试

pytest --cov=.        # 100+ tests, ~89% coverage, incl. the never-send security test

文档

• docs/ — 带截图的完整指南：安装、各类大模型提供方、Gmail OAuth、多账户、集成、MCP 和 Skill、配置、故障排查、测试清单。
• SETUP.md — 5 分钟快速入门。
• PRIVACY.md — 各提供方会将哪些内容发送到设备之外。
• SECURITY.md — 禁止发送约束与漏洞披露。
• CHANGELOG.md — 版本历史。
• CONTRIBUTING.md — 开发环境设置与禁止发送规则。
• CLAUDE.md — Claude Code 项目概览。

构建所用技术

本项目展示了以下契约技能：

• Agent 式编排 — 由模型驱动，逐封邮件选择工具（没有硬编码的处理流程）。
• 函数调用 — CLI Agent 和 MCP 服务共享类型化工具架构（agent.TOOL_SCHEMAS）。
• 多 API 集成 — 在一个流程中集成 Gmail、LLM 和 Todoist。
• 可插拔的大模型提供方 — 一个 llm_client 即可切换 OpenRouter / Ollama / NIM / OpenAI / Anthropic。
• Claude Code 集成 — 原生支持 MCP 服务和 Skill，且两者均无需密钥。

许可证

MIT — 详见 LICENSE。