benethos-mailbox-mcp

Mailbox

メールボックスのプロバイダーを問わず、すべてを扱える単一の REST API と、その Python クライアント、さらにその上で動作する MCP サーバーです。スクリプト、ツール、AI エージェントは、あなたが管理するひとつの窓口を通じてメールを扱えます。

ステータス：ベータ版、バージョン 0.5.2。 実際のアカウントで利用できます。API または設定に破壊的変更がある場合は、変更履歴で告知します。 保存されたデータは、マイグレーションによって引き継がれます。

目次

• 対象となる用途
  • メールで AI エージェントと作業する
  • その他の用途
• 現在できること
• プロバイダー
• 4 つのパッケージ
• 始め方
• ドキュメント
• 開発
• ライセンス

目的

多くの個人や中小企業は、複数のメールアカウントを持っています。GMX や web.de の個人アドレス、Microsoft 365 の会社用メールボックス、ホスティング事業者の info@ アドレス、場合によっては Gmail アカウントなどです。それぞれが独自の方式を使っています。こちらでは IMAP、あちらでは Microsoft Graph という具合です。メールを扱うツールは、それぞれの方式をすべて理解し、パスワードも受け取らなければなりません。

Mailbox はこれを逆転させます。4 つのパッケージで構成されています。mailbox-service は自分のマシンまたはサーバー上で動作し、すべてのアカウントへの接続を管理します。それ以外は、どのプロバイダーでも同じ形式の REST API を通じて、このサービスとのみ通信します。mailbox-client はその API の Python クライアントで、スクリプトやアプリ向けです。MCP サーバーである mailbox-mcp はクライアントを基盤とし、AI エージェントからサービスを利用できるようにします。mailbox-common には、サービスと MCP サーバーが共有するものが含まれています。サービスは、誰が何をできるかを決定します。スクリプト、アプリ、AI エージェントには、それぞれ専用のトークンが発行されます。そのトークンで利用できるのは、許可されたアカウントと操作だけで、それ以上はできません。

これにより、ほかの方法では難しいいくつかのことが簡単になります。

メールで AI エージェントを使う

MCP サーバーを通じて、Claude などの AI エージェントは、利用を許可したすべてのアカウントで作業できます。現在対応しているリクエストの例をいくつか示します。

• 「昨夜から届いたメールは？」
• 「Company XY からの請求書をすべて『会計』フォルダーに移動して。」
• 「今日届いた請求書を税理士に転送して。」
• 「9 月 1 日から 15 日までの Company XY からのメールをすべて表示して。」
• 「今週、添付ファイル付きで届いたメールは？ 請求書を読んで、金額と支払期限を教えて。」
• 「見積もりに関するメールを要約して、返信の下書きを作成して。」
• 「先週のニュースレターを既読にして、アーカイブに移動して。」

権限の設定により、エージェントが自分でメールを送信できるか、人が送信するための下書きだけを作成できるかが決まります。許可の内容には、税理士のアドレスだけなど、メールを送信できる宛先や、1 日に送信できるメールの数を指定することもできます。それ以外の宛先へのメールは拒否されます。請求書フォルダーなど、エージェントが利用できるフォルダーを限定したり、1 週間後に権限を終了したりすることもできます。

そのほかの用途

• アクセスを制御。 経理ツールは、1 つのアカウントの請求書フォルダーだけを読み取り、それ以外にはアクセスできません。送信も削除もできず、メールのパスワードを見ることもありません。受け取るのは専用のトークンだけです。
• 複数アカウントにまたがる自動化。 スクリプトで請求書を整理し、ニュースレターをアーカイブして、注文確認メールを転送します。GMX、Microsoft 365、自社のメールサーバーで同じように動作します。
• 安全策を備えた送信。 ニュースレター送信ジョブは info@ から、固定された宛先リストに対して、1 日に数回までメールを送信します。
• ポーリングではなくイベントに反応。 署名付き Webhook が、たとえば新着メールを自社のシステム、チケットツール、社内ダッシュボードに通知します。
• 追跡可能。 送信のたびに、誰が、いつ、どの許可に基づいて送信したかが監査ログに記録されます。サインインや、ユーザー、トークン、ロール、アカウント、Webhook の変更も同様に記録されます。
• 自社ツール用の統合受信トレイ。 ダッシュボードや小規模な社内アプリで、1 つのクライアントを使ってすべてのアカウントのメールを一覧表示、検索、返信できます。
• セルフホスト可能。 サービスは認証情報を暗号化して保存します。メールはプロバイダーから直接ユーザーのもとに届き、第三者のクラウドを経由することはありません。

現在できること

• アカウント： 送信には SMTP を使用する IMAP。メールアドレスだけで設定できます（自動検出）。Fastmail や Stalwart などの JMAP サーバー、IMAP に対応していないメールボックス向けの POP3（受信トレイのみ）、OAuth サインインによる Microsoft Graph 経由の Microsoft アカウント（Outlook.com、Microsoft 365）、Gmail API 経由の Gmail に対応しています。 認証情報は、データベースの外部に保管するマスターキーを使って暗号化されます（AES-256-GCM）。
• メールの閲覧： フォルダー、一覧、検索に対応し、単一アカウントでも全アカウントでも利用できます。フォルダーをまたいだスレッド、テキスト形式と HTML 形式のメッセージ、添付ファイル、ソースの生データを表示できます。バックグラウンド同期により、メッセージを移動してもメッセージ ID は変わりません。添付ファイルへのリンクを使えば、別のサービスがトークンなしでファイルを一度取得できます。
• メールの作成と送信： 既読状態、スター、キーワードの管理、移動、削除、フォルダー、下書き、および返信、全員に返信、転送を含む送信に対応しています。再試行してもメールは二重送信されません（Idempotency-Key）。
• 変更： 保存した時点以降に作成、変更、削除された各メッセージを変更フィードで確認できます。IMAP、JMAP、POP3、Microsoft、Gmail の各アカウントに対応しており、IMAP サーバーが CONDSTORE を提供している場合は、他のメールクライアントで設定されたフラグも含まれます。Webhook は同じイベントを署名付きで任意の URL に送信します。ローカルネットワーク内のホストも指定できます。
• ユーザーと権限： ユーザー、ロール、アカウントおよび操作ごとの権限付与（フォルダー単位まで設定可能）、有効期限付きの権限付与、API トークン、送信制限（許可する受信者、1 日あたりの送信数）、すべての送信の監査記録、管理操作の監査記録に対応しています。
• MCP サーバー： stdio またはストリーム可能な HTTP 経由で、メールの読み取り、並べ替え、下書きの作成、送信、新着情報の通知を行います。トークンで使用を許可されたツールのみを提供し、実行中も権限に従います。メールの内容は外部テキストとして明示された状態でモデルに渡されます。
• ブラウザーの設定 UI： /ui から、アカウント、ユーザー、権限、トークン、メールの読み書き、送信の監査記録、Webhook、アカウントと同期の状態、管理操作の監査記録、サービスログを確認・管理できます。
• 運用： 暗号化されたバックアップと復元、コンテナーイメージ、Caddy 経由で HTTPS を使って MCP サーバーインスタンスを運用するための Compose ファイルに対応しています。

今後の予定と実施順序については、docs/ROADMAP.md をご覧ください。

プロバイダー

プロバイダー	接続方法	認証情報	状態
GMX、web.de、T-Online、Yahoo、AOL、iCloud、Posteo、mailbox.org、IONOS、Strato、自社のメールサーバー	IMAP + SMTP	アプリパスワード	利用可能
Microsoft 365、Outlook.com	Microsoft Graph	OAuth（プロジェクトのアプリ、または独自のアプリを使用）（設定）	利用可能
Proton Mail	Proton Mail Bridge 経由の IMAP + SMTP	Bridge パスワード	IMAP 対応、未テスト
Gmail / Google Workspace	Gmail API、または IMAP + SMTP	独自の Google Cloud クライアントを使う OAuth（設定）、またはアプリパスワード	利用可能
Fastmail、Stalwart、その他の JMAP サーバー	JMAP	API トークンまたはパスワード	利用可能
IMAP に対応していないレガシーメールボックス	POP3 + SMTP：受信トレイのみ。フォルダー、既読状態、検索には非対応	パスワード	利用可能

非対応：IMAP も API も提供していない Tuta。プロバイダーごとの詳細は docs/CONCEPT.md のセクション 5.3 をご覧ください。

4つのパッケージ

パッケージ	内容	実行場所	詳細
mailbox-service	サービス：REST API、設定 UI、ユーザーと権限、アカウント、暗号化された認証情報、プロバイダーアダプター、バックグラウンド同期	常時	packages/mailbox-service
mailbox-client	REST API の Python クライアント。非同期と同期に対応	独自のコード内	packages/mailbox-client
mailbox-mcp	mailbox-client 上に構築された MCP サーバー	クライアントごとに stdio 経由、または HTTP 経由のサーバーとして	packages/mailbox-mcp
mailbox-common	サービスと MCP サーバーで共有するもの	それらと一緒にインストール	packages/mailbox-common

リリースでは、4つすべてが同じバージョンで PyPI に公開されます。パッケージ名は benethos-mailbox-service、benethos-mailbox-client、 benethos-mailbox-mcp、benethos-mailbox-common です。また、サービスと MCP サーバーは ghcr.io にコンテナーイメージとして公開されます。MCP サーバーは 公式 MCP Registry に io.github.benethos-hub/benethos-mailbox-mcp として登録されており、すべての リリースに Claude Desktop 拡張機能として benethos-mailbox-mcp.mcpb が含まれます。各パッケージには専用の README があります。 サービスと MCP サーバーについては、コンテナーイメージと compose ファイルを使った インストール、起動、設定の方法を説明しています。

はじめに

1. サービスを起動し、最初のユーザーを作成します： packages/mailbox-service。
2. http://127.0.0.1:8080/ui を開き、ワンタイムパスワードで admin として サインインします。自分でパスワードを設定し、アカウントを接続します。
3. スクリプトまたは AI エージェントに必要な権限を持つユーザーとトークンを 用意し（手順）、 エージェントを使う場合は MCP サーバーを追加します。Claude Desktop では リリースから拡張機能としてインストールし、その他のクライアントでは uvx で起動します：packages/mailbox-mcp。

ドキュメント

• docs/CONCEPT.md：設計、API、セキュリティモデル
• docs/ROADMAP.md：各フェーズと完了した内容
• docs/ARCHITECTURE.md：レイヤー、モジュール、新しいコードのルール
• docs/LIMITS.md：すべてのレート制限と、それらの連携方法
• docs/PERMISSIONS.md：ユーザー、ロール、権限
• docs/AUTHENTICATION.md：設定 UI へのサインイン、パスワード、第2要素
• docs/LOGGING.md と docs/AUDIT.md： サービスログと管理操作の監査
• docs/UI.md：設定 UI の各ページの見た目と動作
• docs/REFACTORING.md：コードの構成ができあがった経緯
• docs/IDEAS.md：まとめたアイデア。未決定
• docs/MICROSOFT.md：Microsoft アカウントの接続
• docs/GOOGLE.md：Gmail アカウントの接続、自分の Google クライアント
• docs/openapi.json：API コントラクト。起動中のサービスでは /docs に表示されます
• CHANGELOG.md
• SECURITY.md：脆弱性の報告方法
• containers/：Dockerfile と、運用、開発、テスト用メールサーバー向けの compose ファイル

開発

1 つの uv ワークスペース、1 つのロックファイル、4 つのディストリビューションです。

uv sync
uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run mypy

テストはオフラインで実行されます。CI でもこれらのチェックを実行します。その大半は、組織の再利用可能なワークフローとして実行されます。また、pyproject.toml で許可されている最も低いバージョンでパッケージをインストールしてテストを実行し、それらのバージョンと uv.lock に記載されたすべてのバージョンに既知の脆弱性がないか OSV で確認し、assets/brand/ のブランドアセットも検証します。変更を main に反映するには、これらすべてのチェックに合格する必要があります。実際のテストアカウントを使った手動チェックは live/ にあり、CLAUDE.md に記載されています。同ファイルには、このリポジトリでの作業ルールも記載されています。

ライセンス

MIT です。詳しくは LICENSE を参照してください。