inbox-to-action

inbox-to-action

PyPI で公開され、公式 MCP レジストリ（io.github.tarunlnmiit/inbox-to-action）、 Glama（デプロイ可能なリリース、品質 A）、 および Smithery（MCPB バンドル）に掲載されています。 レジストリマニフェスト（server.json、glama.json）はリポジトリに含まれています。

コマンドひとつで、受信トレイの振り分け、要約、返信の下書き、タスク化までを一度のエージェント処理で実行します。

インストール

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。

---

これを作った理由

ほとんどの人は、受信トレイの処理に4つのツールを使っています。読むためのメールクライアント、やることを記録するタスクマネージャー、時間を確保するカレンダー、そして（最近では）長いスレッドを理解するための AI 要約ツールです。すべてのメッセージに4回対応することになります。

inbox-to-action は、この4つを一度のエージェント処理にまとめます。コマンドひとつを実行するだけで、統合された振り分けレポート、Gmail に保存された返信の下書き、抽出されたタスクを取得できます。ターミナルを離れる必要はなく、メールが自動送信されることもありません。

🔒 下書きのみ — 送信はしません

このツールはメールを送信できません。Gmail の readonly と compose スコープのみを要求します。send スコープはなく、コードベース内のどこにも送信 API の呼び出しはありません（テストで強制されています）。返信は確認して送信できるよう、Gmail の下書きとして保存されます。

メール本文は LLM のプロンプトに渡されるため、悪意のあるメールが自身の分類や返信の下書きを誘導しようとする可能性があります（プロンプトインジェクション）。ただし、すべての下書きは人間による確認のために保存され、自動送信されることはないため、最悪の場合でも、送信しないと判断した下書きが作成されるだけです。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 語超）を 2 行に要約します。
4. 期限付きのタスクを抽出し、ローカルの tasks.md に保存します（--todoist を使うと Todoist にも保存できます）。
5. action_needed のメールへの返信を作成し、Gmail の下書きとして保存します。
6. カレンダーに予定を登録する必要があるメールにフラグを付けます。

最終出力は、各カテゴリのセクション、返信下書きのプレビュー、タスクの概要、カレンダーの一覧を含む単一の triage-report.md です。

アーキテクチャ — エージェントのループ

各メールに対するモデル独自の分類結果に応じて、次に実行されるツールが決まります。パイプラインはハードコードされていません。CLI エージェントと 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 アカウントで、1 つの client_secret.json を再利用できます。アカウントごとに個別のキャッシュ済みトークン（~/.config/inbox-to-action/tokens/<id>.json）が作成されます。accounts ブロックがない場合、ツールは単一のデフォルト Gmail アカウントを使用します（後方互換性があります）。

Claude Code 内で使用する（キー不要）

Claude Code 内で実行する場合、LLM は Claude Code です。プロバイダーキーは不要です。 このリポジトリには、2 つの連携方法が含まれています。

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

これは、バンドルされた Dockerfile（CMD python -m inbox_to_action.mcp_server）から MCP レジストリ（例：Glama）がビルドするものと同じ stdio サーバーです。

スキル

skills/inbox-to-action/ を Claude Code のスキルディレクトリにコピーし、/inbox-to-action と入力します。このスキルは、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 をコピーして作成）で上書きできます。設定は 2 層あります。

• rules — LLM の前に適用する、決定的な 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/ — スクリーンショット付きの詳細ガイド：インストール、各 LLM プロバイダー、Gmail OAuth、複数アカウント、連携機能、MCP と Skill、設定、トラブルシューティング、テストチェックリスト。
• SETUP.md — 5 分で始められるクイックスタート。
• PRIVACY.md — プロバイダーごとに、端末外へ送信される情報を説明します。
• SECURITY.md — 送信しないことの不変条件と、脆弱性の開示方法。
• CHANGELOG.md — バージョン履歴。
• CONTRIBUTING.md — 開発環境のセットアップと、送信しないルール。
• CLAUDE.md — Claude Code 用のプロジェクトマップ。

使用技術

このプロジェクトでは、次の契約スキルを実演します。

• エージェント型オーケストレーション — モデル主導でメールごとにツールを選択します（ハードコードされたパイプラインはありません）。
• 関数呼び出し — CLI エージェントと MCP サーバーで共有される、型付きツールスキーマ（agent.TOOL_SCHEMAS）。
• 複数 API の連携 — Gmail、LLM、Todoist を 1 つのフローに統合します。
• 差し替え可能な LLM プロバイダー — 1 つの llm_client で OpenRouter／Ollama／NIM／OpenAI／Anthropic を切り替えます。
• Claude Code との連携 — MCP サーバーと Skill の両方を、キー不要でネイティブに利用できます。

ライセンス

MIT — LICENSE を参照してください。