your-mail-mcp

your-mail-mcp

メールには、予約番号、ゲートコード、請求書、保証期間、書面で交わした約束など、すでに答えが詰まっています。このサーバーを使えば、AI アシスタントがそれらを見つけられます。読み取り専用です。

たとえば、こんなことを尋ねられます。

• 「6月のフェリーの予約番号を探して。」
• 「去年の夏、ホテルから送られてきた Wi-Fi のパスワードは？」
• 「会計士は VAT について何と回答しましたか？いつのことですか？」
• 「屋根について、私と施工業者の間で交わしたやりとりをすべて時系列でまとめて、誰が何を約束したか要約して。」
• 「今朝、すべてのアカウントに届いたメールのうち、実際に私の対応が必要なものは？」

活用例：

• 質問の意図を理解する検索。 すべての履歴を対象とした全文検索です。すべてのアカウントをひとつのインデックスにまとめ、考えたとおりの言葉で検索できます。
• スマートフォンでのトリアージ。 どこにいても、迷惑メールを除外したうえで、夜間に届いたメールを朝にまとめて確認できます。
• ほかの作業のコンテキストとしてメールを活用。 スレッドからクライアントの要件を取り出し、コーディングや執筆のセッションに取り込めます。
• 起動したままにできるエージェント。 メッセージの送信、削除、移動を行う経路はありません。悪意のあるメールがアシスタントに届いても、読み取られるだけで、それ以上のことは起こりません。定期的なダイジェストや常時稼働するエージェントも、安心して実行できます。

セットアップは2つのファイルを用意して、docker compose up -dを実行するだけです。クイックスタートをご覧ください。

仕組み

セルフホスト型のMCPサーバーです。mbsyncを使って1つ以上のIMAPアカウントをローカルのmaildirにミラーリングし、notmuchでインデックスを作成して、そのインデックスからツール呼び出しに応答します。ClaudeとChatGPTのアプリはOAuth経由のHTTPSで接続し、Claude Code、Codex、Cursor、Claude Desktopは同じマシン上でstdio経由で接続します。どのMCPクライアントでも使えるため、プライバシーを最大限に重視する場合は、ローカルLLMを使うクライアントを接続すれば、メールがマシンの外に出ることはありません。

図の中でメールが移動するのは、常に左から右の方向だけです。設定により、ミラーからの接続は読み取り専用です。Goコードがプロバイダーに対して行う接続は、サーバーが迷惑メール用フォルダーとゴミ箱フォルダーをどう呼んでいるかを把握するための、アカウントごとのIMAP LIST だけです。メールボックスを選択することも、メッセージを取得することもありません。セキュリティでは、このプロセスにできないことの一覧を詳しく説明しています。図のソースは docs/diagrams/how-it-works.htmlです。

クイックスタート

自分のマシンで、自分のために使えます。必要なのは Docker だけです。ghcr.io/wildsurfer/your-mail-mcp のイメージは、amd64 と arm64 向けに CI でビルドされています。

mkdir your-mail && cd your-mail
curl -fsSLO https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/accounts.example.json -o accounts.json

アカウントを accounts.json に記述します。${WORK_PASS} は環境変数から置き換えられるため、ファイル自体にパスワードは保存されません。

{
  "accounts": [
    { "name": "work", "host": "imap.gmail.com", "user": "[email protected]", "password": "${WORK_PASS}" },
    { "name": "personal", "host": "imap.mail.me.com", "user": "you", "password": "${PERSONAL_PASS}" }
  ]
}

パスワードは compose.yaml と同じ場所にある .env に記述します。

# .env
WORK_PASS=your-gmail-app-password
PERSONAL_PASS=your-icloud-app-specific-password

compose.yaml は WORK_PASS と PERSONAL_PASS をコンテナに渡します。別の変数名を使うアカウントの場合は、その名前も environment: に追加する必要があります。

特に時間がかかるプロバイダー関連の注意点は 2 つあります。Gmail では IMAP にアプリパスワードのみ使用でき、アプリパスワードを使うには、まず 2 段階認証を有効にする必要があります。iCloud では user に @icloud.com より前の短い名前を指定します。完全なメールアドレスではログインできません。ファイルの各キーについてはリファレンスを参照してください。

これら 2 つのファイルには、メールのパスワードが保存されています。このディレクトリはバージョン管理に含めず、マシンの外部に保存されるバックアップにも含めないでください。パスワードをファイルに保存したくない場合は、アカウントに password の代わりに pass_cmd を指定してください。これは、Docker シークレットの場合の cat /run/secrets/work_pass や、Mac の security find-generic-password -s your-mail -a work -w のように、シークレットを出力するコマンドです。mbsync は接続時にこのコマンドを実行するため、ディスクにも環境変数にもパスワードは保存されません。リファレンスを参照してください。

docker compose up -d
docker compose logs -f     # watch the first sync

今日の INBOX のメールは、数分以内に検索できるようになります。メールの全履歴はプロバイダーが許可する速度で同期され、どこまで進んだかは status ツールで確認できます。大規模な Gmail アカウントでは、Google が IMAP のダウンロードを 1 日あたり約 2.5GB に制限しているため、完了まで数日かかります。最初のミラーリングでは、.env に SYNC_TIMEOUT=8h を設定してください。詳細はプロバイダーに関する注意事項を参照してください。

次に、クライアントを接続します。Claude Code の場合：

claude mcp add your-mail -- docker exec -i your-mail-mcp your-mail-mcp stdio

スタックの起動後、Cursor と VS Code にはワンクリックで追加できます。

{ "command": "docker", "args": ["exec", "-i", "your-mail-mcp", "your-mail-mcp", "stdio"] }

/plugin marketplace add wildsurfer/your-mail-mcp
/plugin install your-mail@your-mail-mcp

Claude と ChatGPT のスマートフォンアプリは、ベンダーのサーバー経由でコネクターにアクセスするため、サーバーには公開 HTTPS アドレスが必要です。トンネルを使えば、そのアドレスを用意できます。トンネルは外向きに接続するため、自宅のネットワークで待ち受けるものはなく、メールはお使いのマシン上に残ります。

Tailscale をインストールしたら、macOS と Linux のどちらでも同じコマンドを実行します。

tailscale funnel --bg 8080

https://your-machine.your-tailnet.ts.net のようなホスト名が表示されます。--bg を指定すると再起動後も実行されます。そのホスト名をパスフレーズとともに .env に記入し、再起動します。

# .env
PUBLIC_URL=https://your-machine.your-tailnet.ts.net
OAUTH_PASSPHRASE=pick-a-long-one-you-can-type-on-a-smartphone

docker compose up -d

OAUTH_PASSPHRASE は、インターネットとメールの間にある唯一の認証情報です。誤ったパスフレーズを試すたびに1秒かかり、試行は順番に処理されますが、短いパスフレーズではどちらも十分な対策になりません。スマートフォンでも入力できる、長いパスフレーズを使ってください。

Funnel を使うには HTTPS 証明書と、tailnet で Funnel のノード属性を有効にする必要があります。初回は CLI がポリシー行の追加を提案します。tailscale funnel status で公開中の内容を確認でき、tailscale funnel --https=443 off で停止できます。

次にコネクターを追加します。Claude と ChatGPT のスマートフォンアプリではコネクターを追加できないため、Web で一度設定します。その後、スマートフォンにも表示されます。

1. claude.ai または Claude Desktop で 設定 → コネクター を開き、カスタムコネクターを追加します。
2. 名前を付け、URL に <PUBLIC_URL>/mcp を指定します。詳細な OAuth フィールドは空のままにしてください。サーバーがクライアントを自動的に登録します。
3. Claude が同意ページを開きます。OAUTH_PASSPHRASE を入力してください。
4. スマートフォンで Claude アプリを開きます。コネクターはすでに追加されています。作成画面のツールメニューから、会話で有効にしてください。

PUBLIC_URL は、クライアントに入力する値と完全に一致させる必要があります。サーバーは OAuth メタデータの resource として PUBLIC_URL + /mcp を公開します。ここが一致しないことが、コネクターを追加できない最も一般的な原因です。

cloudflared tunnel login
cloudflared tunnel create your-mail

cloudflared tunnel route dns your-mail mail.example.com

tunnel: your-mail
credentials-file: /Users/you/.cloudflared/f9e2….json   # the path create printed
url: http://localhost:8080

cloudflared tunnel run your-mail

claude mcp add --transport http your-mail https://your-host/mcp

codex mcp add your-mail --url https://your-host/mcp
codex mcp login your-mail

お使いのマシンの電源が入っているかどうかにかかわらず、ミラーを稼働させておきたい場合に選んでください。 月に数ドルかかり、実際に考慮すべきトレードオフが1つあります。メールの平文コピー全体が、アプリのパスワードとともに、レンタルしたディスクに保存されます。インストールはクイックスタートにトンネルを追加したもので、他人のコンピューター上で実行します。このボックスには、メールを保存する前にセキュリティ強化が必要です。どちらも docs/server.md に記載されています。

ツール

すべて読み取り専用の11個のツールです。

search、ids、files、count は notmuch クエリ（from:、to:、 subject:、tag:、folder:、date:2026-01-01..2026-06-30、and/or/not による組み合わせ）を受け取り、対象を1つのアカウントに絞るための account を任意で指定できます。また、include_excluded を指定すると迷惑メールやゴミ箱も含められます。迷惑メールやゴミ箱は RFC 6154 SPECIAL-USE に基づいてアカウントごとに特定されるため、フォルダー名や使用言語にかかわらず除外できます。アカウントのミラーへの取り込みがまだ完了していない間は、これら4つのツールはアカウント名と、これまでにインデックスされたメッセージ数を示す注記を先頭に付けます。

添付ファイルは show と thread に一覧表示されます。attachment ツールで1パートずつ取得できます。画像は最大5MBまでインライン表示され、テキストパートはマーク付きテキストとして表示されます。その他のバイナリは、GET /attachment/{id}/{part} への短時間有効な署名付きリンクとして返されます（ベアラートークンも使用できます）。HTTP リスナーがない場合、サイズ超過のバイナリは /index/attachments/ に保存され、ツールは docker cp 用のパスを返します。このディレクトリの上限は1GBで、古いファイルから削除されます。

他の選択肢ではなく、これを選ぶ理由

GitHub には、メール関連の MCP サーバーがおよそ 40 個あります。そのほとんどは IMAP にリアルタイムで接続し、メール送信機能も備えていますが、これはこのサーバーの基盤となる 2 つの選択とは正反対です。その中でも、特に近いものを 2 つ紹介します。

igor47/notmuchproxy は、すでに存在していた中で最も近いものであり、このサーバーが現在の形になった理由の多くを占めています。自分で最新の状態に保つ notmuch アーカイブを読み取り、書き込み機能はなく、ベアラートークンまたはフル OIDC を使用します。未知のプレフィックスを説明付きで拒否するクエリ検証機能は、ここでは validateQuery として再実装されています。異なる点は 2 つあります。notmuchproxy は mbsync と notmuch をすでに実行していることを前提としますが、このサーバーは mbsync の設定を生成し、すべてのアカウントを並列で同期し、IMAP を通じて迷惑メールとゴミ箱を検出します。また、account パラメーターがありません。すでに満足のいく notmuch の構成を運用しているなら、notmuchproxy のほうが導入しやすいため、こちらではなくそちらを使ってください。

hgn/mcp-server-notmuch は stdio のみをサポートしているため、1 台のマシンで 1 つのクライアントを使用する構成です。また、信頼できないコンテンツの扱いは、今回調査した中で最も優れています。すべてのメールテキストのバイト列に一箇所で印を付け、個々のツールがそれを忘れることのないようにする、このサーバーの単一の render() 集約点は、同プロジェクトの render.py に着想を得ています。

ソースコードで確認した主張と README から引用した主張を含む調査全体は、 docs/research/email-mcp-landscape.md にあります。

セキュリティ

大切なメールボックスに接続する前に、これをお読みください。

書き込みはできません。 すべてのアカウント向けに生成される mbsync 設定には、Sync Pull、Create Near、Remove Near、Expunge None が含まれます（expunge_local が設定されたアカウントでは、ローカルファイルのみを削除する Expunge Near が含まれます）。このファイルはプログラム自身が書き込むため、内容を編集してプッシュする設定に変えることはできません。Remove Near が作用するのはローカル側だけです。サーバー上のフォルダーが削除または名前変更されても、メールをすべて保持したローカルコピーは残り、削除されるのは空のローカルフォルダーだけです。 Go コード内で実行される IMAP 操作は LIST だけです。アカウントごとに起動時と1時間ごとに実行し、迷惑メールフォルダーとゴミ箱フォルダーを見つけます。exclude_folders を手動で設定したアカウントでは、この操作さえ実行されません。メッセージの送信、削除、移動、タグ付けを行う経路はなく、どのアカウントに対しても書き込み権限を保持しません。

削除したメールはミラーに残ります。 サーバー上で削除したメールはディスク上に保持され、notmuch の deleted タグによって検索結果から非表示になります。ローカルコピーを物理的に削除するには、アカウントに expunge_local: true を設定してください。それでもアカウントに書き込むことはありませんが、その場合、ミラーはバックアップとして機能しなくなります。リモート側で消えたものは、次回の同期時にローカル側でも消えます。

検証状況について。 作者兼運用者は1人で、実際のアカウント3つ（iCloudが1つ、Gmailが2つ）で使用しています。第三者によるセキュリティレビューはなく、ほかに導入した人もいません。notmuchproxy のスター数はゼロですが、本プロジェクトよりも本番環境での実績を納得できる形で示しています。

コンテナ内ではパスワードが平文で保存されます。 アカウントのパスワードは環境変数から取得され、起動時にファイルモード 0600 の mbsync 設定ファイルへ書き込まれます。このファイルは暗号化されません。コンテナの環境変数またはこのファイルを読み取れるものは、パスワードも読み取れます。代わりに pass_cmd を設定したアカウントでは、シークレットはコマンドが読み取る場所（Docker シークレットやキーチェーンなど）に保持され、環境変数と生成されたファイルにはコマンドのみが保持されます。ただし、プログラム自身が実行する IMAP の LIST では、パスワードがメモリ上に渡されます。ディスク暗号化、コンテナへの exec アクセス権、ホストへのアクセスは運用者の責任です。このサーバーは、保存時の認証情報の暗号化を保証しません。

パスフレーズは1つ、同意も1つです。 OAUTH_PASSPHRASE は定数時間で検証され、1つの共有シークレットでサーバー全体へのアクセスを制御します。ユーザーごとの認証情報システムではなく、パスフレーズを持つ人は全員、メールボックス全体を閲覧できます。また、保存データは暗号化されません。パスフレーズとメールのパスワードは、同じように慎重に扱ってください。

メールボックスはシークレットストアです。 パスワードのリセット、サインインコード、マジックリンクはすべてメールで届くため、誤った相手や誤った AI セッションにアクセス権が渡ると、読み取り権限だけでアカウントを乗っ取るのに十分です。読み取り専用の設計と信頼できないコンテンツを示すマーカーによって、書き込み経路と命令を伝える経路は排除されていますが、メールの内容が無害になるわけではありません。信頼できるクライアントを接続してください。エージェントのワークフローで専用の受信トレイが必要な場合は、専用のアドレスが必要です。それは別のツールの役割です。

既知の問題。 search のスレッド概要には、該当スレッド内のすべてのメッセージの表示名が含まれます。表示名は送信者が指定します。デフォルトで除外されるフォルダー（迷惑メール、ゴミ箱）内のメッセージでも、本文が表示されることはありませんが、この方法で攻撃者が選んだ名前を表示させることができます。thread と show はこの問題の影響を受けません。このリリースでは修正されていません。

インターネットに公開するサーバーについては、 docs/server.md に、効果の大きい順に強化手順を記載しています。

リファレンス

• アカウントファイル：デフォルト値を含むすべてのキー。
• 環境変数：同期間隔とタイムアウト、リスナーのアドレス、INIT_MIRROR。
• プロバイダーに関する注記：iCloud、Gmail、Dovecot。
• トラブルシューティング：起動時に拒否されるケースと、迷惑メールが除外されないことがある理由。
• Docker を使用しない場合：リリースバイナリと、それらがシェル経由で実行するもの。
• サーバーでの実行：インストールスクリプト、セキュリティ強化、Caddy を使った独自ドメインの設定。
• 0.4.x からのアップグレード。
• 設計仕様とメール MCP サーバーの調査。