mcp4mail

mcp4mail

MCP サーバーとして利用できるメールボックスです。IMAP アカウントを接続すると、AI アシスタントが OAuth 2.1 認証を通じてメールを読んだり検索したりできるようになります。mcp4mail.online でホストされており、オープンソースでセルフホストも可能です。

自分で実行すれば、認証情報がマシンの外に出ることはありません。 ホスト型メールコネクターでは、IMAP パスワードを必ず他人のサーバーに保存することになります。mcp4mail なら、代わりに自分のデータベースに保存できます。docker compose up を実行するだけで準備できます。セルフホスティングガイドをご覧ください。

mcp4mail はまだ新しいプロジェクトで、私たち自身も利用しています。現在は、以下に記載した 14 個のツールを提供しています。アカウントやフォルダーの一覧表示、ヘッダーの検索、メッセージの閲覧、添付ファイルのダウンロード、連絡先の検索ができます。メールボックスの変更（フラグ設定、移動、ゴミ箱への移動、フォルダーの作成、下書きの保存、送信）もできますが、メールボックスの所有者が「AI に変更を許可する」を有効にし、その権限にチェックを入れた場合に限られます。すべてのメールボックスはデフォルトで読み取り専用です。また、send_message は、人間が「送信」を押した後に送信されるメールを準備するだけです。

試してみる

• ホスト型： mcp4mail.online にアクセスして登録し、IMAP アカウントを接続して、https://mcp4mail.online/mcp を MCP クライアントに追加します。
• セルフホスト： cp .env.example .env を実行して内容を入力し、docker compose up -d を実行します。セルフホスティングガイドをご覧ください。

このプロジェクトは主に、mcptask.online を通じてオーケストレーションされた AI 開発者が開発しています。開発の様子をライブでご覧ください：https://mcptask.online/live

このプロジェクトの開発方法

これは実際のオープンソース製品であると同時に、公開デモでもあります。タスクはmcptask.onlineで人が作成し、ランナー（自社のマシン上で mcptask runner によって制御される Claude Code）が引き受けます。すべての変更は同じ手順をたどります。タスク → ブランチ → プルリクエスト → テストと CI → マージ → mcp4mail.online へのデプロイです。人もランナーも、main に直接プッシュすることはありません。ブランチにはリポジトリのルールセットが適用されており、スクワッシュマージを許可するには、プルリクエストがオープンであること、履歴が直線的であること、ステータスチェック（セキュリティスキャン、lint、単体テスト、システムテスト）がすべて成功していることが求められます。

ライブでご覧ください：https://mcptask.online/live

ご自身で確認する場合は、次の場所をご覧ください。各 PR にタスクへのリンクがあり、失敗したものも含む CI の実行結果が表示されるプルリクエストタブ、ランナーが従う指示を記載したCLAUDE.mdと.claude/、そしてCI 設定です。

タスクの概要を作成し、プルリクエストをレビューし、何をリリースするかを決めるのは、今も人間です。ランナーはタスクを最初から最後まで実行しますが、何を開発するかを決めるわけではありません。ランナーはこのサービスの利用枠を持つユーザーであり、無料でも無制限でもありません。

MCP ツール

AI クライアントを https://mcp4mail.online/mcp（またはご自身のインスタンスの /mcp URL）に接続して、サインインしてください。 Claude、Claude Code、ChatGPT、Cursor、VS Code の手順はこちらをご覧ください：docs/mcp-clients.md。

ツール	機能
list_mail_accounts	接続したメールアカウントを一覧表示します。他のツールで使用する ID も表示されます。
get_mail_account	1 つのアカウントの接続情報を表示します（パスワードは表示しません）。
list_folders	1 つのアカウントのフォルダーを一覧表示します。
search_messages	件名、送信者、宛先、添付ファイル名、日付で検索します。
get_message	1 件のメッセージを読み込みます。
get_attachment	メッセージの添付ファイルをダウンロードします。短時間有効なリンク、または inline: true を指定すると、MCP の回答内にファイルそのものを含めます（最大 5 MB）。
search_contacts	これまでにやり取りしたアドレスを検索します。
get_outgoing_status	send_message に渡したメールが送信されたかどうかを確認します。
set_flags	メッセージにフラグを付ける、または既読／未読にします。書き込み。
move_message	メッセージを別のフォルダーに移動します。書き込み。
trash_message	メッセージをゴミ箱に移動します。書き込み。
create_folder	フォルダーを作成します。書き込み。
create_draft	下書きを保存します。書き込み。
send_message	メールを準備します。承認後にのみ送信されます。書き込み。

書き込みツールは、メールボックスの所有者が「Allow the AI to make changes to this mailbox」を有効にし、 各ツールの動作にチェックを入れた場合にのみ、そのメールボックスで使用できます。それ以外の場合は拒否されます。詳しくは 下記をご覧ください。send_message が自動で送信することはありません。リンク付きのメールが届き、［送信］を押したときにのみメッセージが送信されます。

セルフホスト

cp .env.example .env    # fill in the values
docker compose up -d

まず docs/self-hosting.md をお読みください。必要な環境変数、HITCH_RESOURCE_URI を公開 URL と完全に一致させる必要がある理由、TLS、メールボックスのパスワードの保存方法について説明しています。

技術スタック

Ruby 3.4、Rails 8.1、PostgreSQL、Hotwire（Turbo + Stimulus）、Tailwind CSS、Solid Queue / Cache / Cable。

開発

bin/setup   # install gems, prepare the database, start the dev server
bin/dev     # web server + Tailwind watcher
bin/ci      # rubocop, security audits, tests, system tests

PostgreSQL がローカルで実行されている必要があります。デフォルトの設定では、ローカルソケット経由で OS ユーザーとして接続します。

シークレット

このリポジトリは公開されています。シークレットがコミットされることはありません。config/master.key、.env*、credentials.yml は git で無視され、本番環境のシークレットは環境から取得されます。

メールボックスのパスワードは Active Record Encryption を使用して保存時に暗号化されます。本番環境では、bin/rails db:encryption:init でキーを生成し、暗号化された認証情報（active_record_encryption.*）または環境変数 ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY、 ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY、ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT を通じて設定してください。開発環境とテスト環境では、マシンごとの tmp/local_secret.txt から使い捨てのキーを導出します。

メールアカウント

mcp4mail は、ユーザー名とパスワードを使って通常の IMAP でメールボックスに接続します。プロバイダーがアプリパスワードを提供している場合は、必ずアプリパスワードを使用してください（Gmail、iCloud、Fastmail、Outlook.com、Yahoo などが提供しています）。そうすれば、データベースに保存される情報を単独で無効にでき、アカウント全体の鍵にならずに済みます。 Gmail も同じ方法で使用できます。2 段階認証を有効にし、アプリパスワードでサインインしてください。Google Workspace アカウントでは、管理者が IMAP またはアプリパスワードを無効にできます。再び有効にできるのも管理者のみです。 パスワードの保存方法と、復号できるユーザーについては、 セルフホストガイドのセキュリティに関する説明をご覧ください。

MCP エンドポイント：設計上、読み取り専用

すべてのメールボックスは、設定を変更するまでは読み取り専用です。「メールアカウント」ページにある各メールボックスには、「AI にこのメールボックスへの変更を許可する」というスイッチが1つあり、デフォルトではオフになっています。

• オフ（デフォルト）：AI は読み取りと検索のみ可能です。メールボックスを変更するツールはすべて拒否され、モデルにはメールボックスが読み取り専用であることを伝えるメッセージが表示されます。また、拒否は監査ログに denied として記録されます。
• オン：スイッチの下にチェックボックスが表示され、そのメールボックスで AI に許可する操作を選択できます。既読にする、フラグを付ける（set_flags）、メッセージを移動する、フォルダーを作成する（move_message、create_folder）、下書きを作成する（create_draft）、送信と返信（必ずユーザーの承認後に実行）（send_message）、ゴミ箱に削除する（trash_message）を選べます。スイッチをオンにすると、すべてにチェックが入ります。チェックが外れているツールは、読み取り専用のメールボックスの場合と同じように拒否されます。list_mail_accounts と get_mail_account により、モデルは許可されている操作を確認できます。

ツールレジストリは、読み取り専用かつ非破壊的でも、書き込みツールとして明示的に宣言されてもいないツール（McpTools::ApplicationTool での write_tool destructive: ..., permission: ...。permission は上記のチェックボックスのいずれか）を登録した状態では起動できません。そのため、誤って書き込みツールとして登録されることはありません。書き込みツールは readOnlyHint: false を通知し、独自の destructiveHint を宣言します。

読み取り専用が何を意味し、何を意味しないのかを明確に説明します。

• スイッチと対応するチェックボックスが有効になっていない限り、メールボックスが変更されることはありません。フォルダーは IMAP の EXAMINE で開かれるため、読み取りによってメッセージが既読になることもありません。

• 接続した AI クライアントから要求があれば、メールは読み取られます。信頼できるクライアントのみ接続してください。

• メッセージヘッダー（送信者、受信者、件名、日付、フラグ、サイズ）のコピーが独自のデータベースに保存され、15分ごとに更新されます。そのため、検索のたびにメールサーバーへ問い合わせることはありません。

• スコープ制限。 すべてのツールは、サインイン中のユーザー自身のメールアカウントを通じてデータを取得します。ユーザー本人のものではないアカウント ID は、ツールのコードが実行される前に拒否されます。

• レート制限。 Hitch はユーザーとクライアントの組み合わせごとに制限を適用します（1分あたり120リクエスト）。さらに、ユーザーごとに、すべてのクライアントを通じたツール呼び出しの上限が適用されます（1分あたり240回）。

• 監査ログ。 すべての呼び出しについて、ユーザー、クライアント、ツール、アカウント、結果、返された行数、所要時間が mcp_audit_events に記録されます。引数は保存されません。

• 検索ガード。 1ページあたりの結果は最大50件です。また、各アカウントには検索回数（10分あたり60回）と返される行数（1時間あたり1,000行）の上限が設けられているため、ループが暴走してメールボックス全体を走査することはできません。

よくある質問

Gmail APIやMicrosoft Graph APIではなく、なぜIMAPを使うのですか？ 対象ユーザーは独自のIMAPホストを使っており、呼び出せるベンダーAPIがありません。ユーザー名とアプリパスワードを使う標準のIMAPはどこでも動作するため、GmailやMicrosoftのOAuthは不要です。メールアカウントをご覧ください。

メールのパスワードはどこに保存され、誰が復号できますか？ PostgreSQLにActive Record Encryption（AES-256-GCM）で暗号化して保存されます。IMAP接続を開く際にメモリ上でのみ復号され、表示、ツールによる返却、ログへの記録は一切されません。暗号化キーを持つ人は誰でも復号できます。セルフホストする場合は、ご自身が該当します。

AIは独自の判断でメールを送信したり削除したりできますか？ いいえ。所有者が「AIによる変更を許可」を有効にし、許可する操作にチェックを入れるまでは、すべてのメールボックスは読み取り専用です。有効にした場合でも、send_messageは、送信ボタンを押した後に送信されるメールを準備するだけです。また、削除はtrash_messageによってゴミ箱に移動します。設計上の読み取り専用をご覧ください。

メールは保存されますか？ 保存されるのは、送信者、宛先、件名、日付、フラグ、サイズなどのメッセージヘッダーのみです。検索のたびにメールサーバーへアクセスしないよう、15分ごとに更新されます。メッセージ本文は、AIから要求されたときにメールサーバーから読み込まれます。

Outlook、Exchange、Gmailで使えますか？ プロバイダーがアプリパスワードを使ったIMAPを提供していれば使えます。Gmail、iCloud、Fastmail、Outlook.com、Yahooが該当します。ExchangeサーバーでIMAPが許可されているかどうかは、管理者の判断によります。メールアカウントをご覧ください。

無料ですか？ はい。MITライセンスで、セルフホストも可能です。mcp4mail.onlineで提供しているホステッドサービスも、同じコードで運用されています。

コントリビューション

CONTRIBUTING.mdをご覧ください。bin/ciがパスする必要があります。

ライセンス

MIT