Mail Shadow MCP

AI エージェントのためのプライベートで安全、そしてインテリジェントな受信トレイ

AI にメールへの直接アクセスを許可するのはやめましょう。代わりに、安全で超高速、かつ機能豊富な「シャドー」コピーを使いましょう。

---

mail-shadow-mcp でできること

すべてのメールを読み、重要なものを正確に把握し、数秒で質問に答えてくれるパーソナルアシスタントがいると想像してみてください。誤動作や幻覚を起こす AI によって、実際のメールボックスが危険にさらされることはありません。

mail-shadow-mcp を使えば、AI（OpenClaw、Hermes Agent、Claude、Cursor、その他のカスタムエージェントなど）に次のように尋ねることができます。

• 「過去3日間に Amazon から請求書が届きましたか？」
• 「プロジェクトの状況について、上司から届いた最新のメールスレッドを要約してください。」
• 「『Project』フォルダーにある未読メールをすべて要約してください。」
• 「来週のフライト確認メールが受信トレイにあるか確認してください。」
• 「添付ファイルのある、『[email protected]』からのメールをすべて探してください。」
• 「受信トレイに迷惑メールらしきものはありますか？」

---

なぜこれが必要なのでしょうか？

ほとんどの AI エージェントは、メッセージを「見る」ためにメールへの直接アクセス（IMAP）を必要とします。これは危険です。エージェントが有効な IMAP 認証情報を持つと、あなたと同じ権限を持つことになり、メールの閲覧、移動、削除、さらには送信まで可能になります。幻覚、誤解された指示、あるいはバグが一度でも起きれば、AI が誤って受信トレイ全体を削除したり、意図しない返信を送信したり、認証情報を第三者に漏らしたりする可能性があります。

mail-shadow-mcp は「セーフゾーン」を作成することで、この問題を解決します。

1. シャドーコピー： 実際のメールサーバーに接続する代わりに、メールのローカルな高速「シャドー」データベース（SQLite）を作成します。これにより、通常の IMAP では実現できない機能も利用できます。サーバーとの通信を一切行わず、すべてのフォルダーとアカウントを対象にした即時の全文検索、既読／返信済みの状態、添付ファイル、日付範囲、送信者による複雑なフィルタリングが可能です。複数のメールボックスを同時に扱う場合も同様に機能し、設定にアカウントを追加するだけです。
2. 完全なプライバシー： AI エージェントがやり取りするのは、このローカルデータベースだけです。IMAP 認証情報は同期エンジン専用であり、MCP ツール呼び出しを通じて公開されたり、応答でエージェントに返されたりすることはありません。
3. 「セーフティネット」（ソフト削除）： AI にメールの「削除」を頼んでも、実際には削除されません。指定した「ゴミ箱」フォルダーに移動するだけです。問題が起きても、フォルダーを確認し、個々のメールを復元したり、自分で完全に削除したりできます。すべての操作をあなたが完全に管理できます。

[Remote IMAP Server] ──IMAP──▶ [Sync Engine] ──▶ [SQLite FTS5] ◀──▶ [MCP Server] ◀──▶ [AI Agent]

---

はじめに

mail-shadow-mcp の実行には、Docker の使用を推奨します。コンテナー内で実行することで、同期エンジン、認証情報、データベースを AI エージェントから完全に隔離できます。エージェントは HTTP 経由で接続します。エージェントがホストのファイルシステムや IMAP パスワードにアクセスすることはなく、MCP API のみを利用できます。

Docker を使わずにローカルで実行したい場合は、リリースページからコンパイル済みのバイナリーをダウンロードし、代わりに stdio トランスポートを使用できます。ただし、その場合はエージェントのプロセスと mail-shadow-mcp が同じユーザーコンテキストを共有するため、前述の隔離によるメリットが低下します。

ステップ 1 — コンテナを起動してサンプル設定を生成する

設定用とデータ用のローカルディレクトリを作成し、最初に実行してサンプル設定を生成します。

mkdir -p ./config ./data

docker run --rm \
  -v ./config:/config \
  -v ./data:/data \
  ghcr.io/dryas/mail-shadow-mcp:latest

コンテナは config.yaml が存在しないことを検出すると、注釈付きのサンプル設定を ./config/ にコピーし、メッセージを表示して終了します。

ステップ 2 — 設定ファイルを編集する

./config/config.yaml（または /config ボリュームをマウントした場所）を開き、IMAP の詳細を入力します。

sync_interval_min: 15

database:
  path: "/data/mail.db"

attachment_dir: "/data/attachments"

transport: http
http_addr: ":8080"
http_bearer_token: "your-secret-token"   # generate one: openssl rand -hex 32

accounts:
  - id: "[email protected]"
    host: "imap.example.com"
    port: 993
    username: "[email protected]"
    password: "$WORK_IMAP_PASS"          # resolved from environment variable at startup
    tls_mode: tls                        # tls (default) | starttls | none
    tls_skip_verify: false               # set true for self-signed certificates
    folders: ["INBOX", "Archive"]        # omit to sync all folders
    idle_folders: ["INBOX"]              # optional: instant new-mail push via IMAP IDLE
    trash_folder: "llm_delete"           # target folder for soft-deletes via delete_mail

環境変数でパスワードを指定する場合： IMAP パスワードを設定ファイルに直接記述する代わりに、$VARIABLE_NAME のプレースホルダーを使用します。mail-shadow-mcp は起動時に、コンテナの環境変数から値を取得します。上の例では、password: "$WORK_IMAP_PASS" とすると、コンテナは WORK_IMAP_PASS 環境変数の値を読み込みます。コンテナの起動時に -e WORK_IMAP_PASS=your_password_here で値を渡します（ステップ 1 または 3 を参照）。こうすれば、設定ファイルに平文のパスワードが残りません。

folders： 同期する IMAP フォルダーのリストです。省略すると、すべてのフォルダーが同期されます。実際に必要なフォルダー（例：["INBOX", "Archive"]）に絞ると、データベースのサイズを抑え、初回同期を高速化できます。

idle_folders： mail-shadow-mcp が永続的な IMAP IDLE 接続を開くフォルダーの任意のリストです。メールサーバーから「EXISTS」通知が送られると、次のポーリング間隔を待たずに同期がすぐに開始されるため、新着メールを数秒で受け取れます。このリストは短くしてください。各項目について、コンテナの稼働中は IMAP 接続が 1 つ開いたままになります。ベストプラクティスは、ここには "INBOX" だけを追加するか、項目を省略して通常のポーリングを利用することです。

trash_folder： AI エージェントが delete_mail ツールを呼び出したときに、mail-shadow-mcp がメールを移動する IMAP フォルダーです。このフォルダーは、あらかじめメールサーバー上に作成しておく必要があります。設定されていない場合、delete_mail はエラーを返して何も実行しません。これは安全なデフォルト動作です。ゴミ箱フォルダー内のメールは、すべての MCP クエリ結果（検索、最近のアクティビティ、スレッド）から自動的に除外されるため、そのフォルダーが同期設定に含まれているかどうかにかかわらず、エージェントから再び見えることはありません。注：trash_folder を別のフォルダー名に変更すると、以前のゴミ箱フォルダーは除外されなくなり、次回の同期後にその内容がエージェントから再び見えるようになります。切り替える前に、古いフォルダーを手動で空にしてください。

http_bearer_token： MCP HTTP エンドポイントを保護する秘密トークンです。AI エージェントからのすべてのリクエストには、Authorization: Bearer <token> としてこのトークンを含める必要があります。これがないと、ポートにアクセスできる人なら誰でも MCP サーバーと通信できます。したがって、http トランスポートを使用する場合は必ず設定してください。次のコマンドで安全なランダムトークンを生成します。

# Linux / macOS / WSL
openssl rand -hex 32

# Windows PowerShell
[System.Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))

出力を設定ファイルにコピーし、同じ値を AI エージェントにも渡します（ステップ 4 を参照）。

ステップ 3 — コンテナを起動する

docker run -d \
  --name mail-shadow-mcp \
  --restart unless-stopped \
  -v ./config:/config:ro \
  -v ./data:/data \
  -e WORK_IMAP_PASS=your_password_here \
  -p 8080:8080 \
  ghcr.io/dryas/mail-shadow-mcp:latest

これで、MCP サーバーに http://localhost:8080/mcp からアクセスできます。

ビルド済みのマルチアーキテクチャイメージ（linux/amd64、linux/arm64）は、リリースのたびに GitHub Container Registry に公開されます。

docker pull ghcr.io/dryas/mail-shadow-mcp:latest

ステップ 4 — AI エージェントを接続する

Docker で実行する場合、MCP サーバーには HTTP 経由でアクセスできます。これはリモートエージェントだけでなく、Claude Desktop でも利用できます。次の内容をエージェントの設定に追加してください。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "mail_shadow": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

mail-shadow-mcp が別のマシンで動作している場合は、localhost をサーバーの IP アドレスまたはホスト名に置き換えてください。

Hermes Agent（config.yaml）：

  mail-shadow:
    url: http://localhost:8080/mcp
    headers:
      Authorization: Bearer your-secret-token

OpenClaw（~/.openclaw/openclaw.json）：

{
  "mcp": {
    "servers": {
      "mail_shadow": {
        "url": "http://localhost:8080/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer your-secret-token"
        }
      }
    }
  }
}

代替手段：ローカル stdio（コンパイル済みバイナリ、Docker 不要）

Docker ではなくバイナリを直接実行する場合は、command 形式を使用します。

{
  "mcpServers": {
    "mail_shadow": {
      "command": "/path/to/mail-shadow-mcp",
      "args": ["serve", "--config", "/path/to/config.yaml"]
    }
  }
}

これで完了です。AI がメールを安全に検索して読めるようになりました。

---

安全性：削除されるものは何もありません

mail-shadow-mcp は AI エージェントに delete_mail ツールを提供しますが、このツールが破壊的な IMAP コマンドを発行することはありません。エージェントがこのツールを呼び出すと、次の処理が行われます。

1. MCP サーバーがローカルデータベースでメールを検索します。
2. 短時間だけ使用する IMAP 接続を開き、IMAP MOVE を実行して、メッセージを config.yaml で指定した trash_folder（例："llm_delete"）に移動します。
3. ローカルデータベースのエントリを削除し、すべての MCP クエリ結果からゴミ箱フォルダーを永久に除外します。フォルダーが同期されているかどうかにかかわらず、エージェントが移動したメールを再び見ることはありません。
4. メールはIMAP サーバー上にそのまま残り、ゴミ箱フォルダーに安全に保管されます。いつでも自分で内容を確認したり、元に戻したり、完全に削除したりできます。

AI エージェントは IMAP に直接アクセスできません。メッセージの消去、フォルダーの空にする操作、またはこの制御された移動以外の書き込みコマンドを実行することはできません。アカウントに trash_folder が設定されていない場合、delete_mail はエラーを返し、何も実行しません。

---

技術的な詳細

MCP ツール

ツール	説明
list_accounts_and_folders	同期済みのすべてのアカウントとそのフォルダーを一覧表示します
get_recent_activity	オプションのフィルター（is_read、has_attachments、ページネーション）を指定して、最新の N 件のメールを取得します
get_email_content	1 件のメールの本文全体、既読・返信済みの状態、添付ファイルの一覧を取得します
search_emails	件名／送信者／日付／フォルダー／is_read／sent_by フィルターを指定できる FTS5 全文検索を行います
get_thread	指定したメールと同じスレッドに属するすべてのメールを日付の昇順で取得します
download_attachments	IMAP から添付ファイルを取得し、ディスクに保存します
get_download_link	添付ファイルの一時的な HTTP ダウンロード URL を生成します（オプションの代替手段）
delete_mail	メールを設定済みのゴミ箱フォルダーに移動してソフト削除します（IMAP MOVE を使用し、完全には削除しません）

機能の概要

• ローカルシャドウデータベース — メールはローカルの SQLite データベースに同期されます。AI エージェントが IMAP サーバーに直接接続することはありません
• 読み取り専用の同期 — 同期エンジンは読み取りコマンド（SELECT、UID FETCH）のみを発行します。メールサーバーに STORE、APPEND、EXPUNGE が送信されることはありません
• 差分同期 — 既知の UID より新しいメッセージのみを取得します
• 全文検索 — 本文の高速な検索に SQLite FTS5 インデックスを使用します
• マルチアカウント — 任意の数の IMAP アカウントを同時に同期できます
• IMAP IDLE — オプションのリアルタイムプッシュ通知に対応します。次のポーリング間隔を待たずに、新着メールを数秒以内に検出します
• 既読・返信済みの状態 — is_read フラグと is_replied フラグは IMAP から同期され、フィルターとして使用できます
• スレッド表示 — get_thread は Message-ID／In-Reply-To ヘッダーをたどって、メールのやり取り全体を取得します
• ページネーション付きの結果 — すべての一覧ツールは total_count を返すため、エージェントは大量の結果をページごとに取得できます
• 必要に応じた添付ファイル取得 — 添付ファイルは明示的に要求された場合にのみ、IMAP から取得されます
• 柔軟なトランスポート — ローカルツール（Claude Desktop）には stdio、リモートおよび Docker でのデプロイには http（StreamableHTTP）または sse を使用できます
• Docker 対応 — 公式マルチアーキテクチャイメージ（linux/amd64、linux/arm64）は、リリースごとに ghcr.io に公開されます

設定リファレンス全体

sync_interval_min: 15

database:
  path: "data/mail.db"      # path to the local SQLite shadow database

attachment_dir: "data/attachments"  # base directory for downloaded attachments

# Optional: log file and level. Omit log_file to write to stderr (default).
# log_file: "logs/mail-shadow-mcp.log"  # append mode; directory is created automatically
# log_level: info                        # debug | info (default) | warn | error
# log_format: text                       # text (default) | json

# MCP transport mode.
# stdio (default) — stdin/stdout, used by Claude Desktop and most local tools.
# http            — StreamableHTTP, recommended for Docker and remote deployments.
# sse             — legacy SSE transport (prefer http unless your client requires SSE).
# transport: stdio
# http_addr: ":8080"                      # bind address for http/sse (default: :8080)
# http_base_url: "http://localhost:8080"  # sse only: externally reachable base URL
# http_bearer_token: ""                  # recommended: set a secret token to protect the HTTP endpoint
                                         # generate one with: openssl rand -hex 32

# Optional: lightweight HTTP server for temporary attachment download links.
# fileserver_port: 8787               # TCP port to listen on (disabled if omitted)
# fileserver_ttl_min: 15              # minutes before a link expires (default: 15)
# fileserver_host: "localhost"        # hostname/IP shown in generated URLs

accounts:
  - id: "[email protected]"
    host: "imap.example.com"
    port: 993
    username: "[email protected]"
    password: "$WORK_IMAP_PASS"     # or plain text; prefix with $ to read from env var
    tls_mode: tls                   # tls (default, implicit TLS, port 993)
                                    # starttls (STARTTLS upgrade, port 143)
                                    # none (no encryption — localhost/testing only)
    tls_skip_verify: false          # set true for self-signed certificates
    folders: ["INBOX", "Archive"]   # optional: omit to sync all folders
    # idle_folders: ["INBOX"]       # optional: folders watched via IMAP IDLE for instant new-mail notification
    # trash_folder: "llm_delete"    # optional: target folder for delete_mail (soft-delete via IMAP MOVE)

Docker Compose

services:
  mail-shadow-mcp:
    image: ghcr.io/dryas/mail-shadow-mcp:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config/config.yaml:/config/config.yaml:ro   # your config — mount read-only
      - ./data:/data                                  # persistent DB + attachments
    environment:
      - WORK_IMAP_PASS=your_password_here             # referenced as $WORK_IMAP_PASS in config

環境変数を使ったパスワードの指定： config.yaml では、パスワードを $ENV_VAR として参照できます。サーバーは起動時にその値を解決します。docker-compose の environment: または docker run の -e を使って値を渡してください。これにより、設定ファイルに平文のパスワードが残ることはありません。

TLS モード

tls_mode	ポート	説明
tls	993	暗黙的 TLS（デフォルト）
starttls	143	STARTTLS によるアップグレード
none	143	暗号化なし — localhost／テスト専用

自己署名証明書を許可するには、tls_skip_verify: true を設定します。

認証（Bearer Token）

http または sse トランスポートを使用する場合は、必ず http_bearer_token を設定してください。設定しないと、ポートにアクセスできる人なら誰でも MCP エンドポイントに接続できます。

暗号学的に安全なトークンを生成します。

# Linux / macOS / WSL
openssl rand -hex 32

# PowerShell
[System.Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))

IMAP IDLE（リアルタイムプッシュ）

デフォルトでは、mail-shadow-mcp は sync_interval_min 分ごとに新着メッセージを確認します。ほぼ即時の通知が必要なフォルダーでは、IMAP IDLE を有効にします。

accounts:
  - id: "[email protected]"
    # ...
    idle_folders: ["INBOX"]   # IDLE runs on top of regular polling

• idle_folders の各エントリーにつき、専用の IMAP 接続が 1 つ開かれます
• サーバーから EXISTS 通知が送信されると、すぐに同期が開始されます
• その他すべてのフォルダーでは、通常のポーリングがこれまでどおり継続されます
• サーバーが IDLE をサポートしていない場合は、自動的にポーリングにフォールバックします
• 接続エラーが続く場合は、指数バックオフ（30 s → 5 min）が適用されます

添付ファイルダウンロードサーバー

オプションの組み込み HTTP サーバーを使用すると、AI エージェントは添付ファイル用の一時的な使い捨てダウンロードリンクを生成できます。エージェントが通常のチャネル経由でファイルを転送できない場合の代替手段として便利です。

config.yaml で有効にします。

fileserver_port: 8787        # TCP port to listen on
fileserver_ttl_min: 15       # minutes before a link expires (default: 15)
fileserver_host: "localhost" # hostname/IP shown in generated URLs

ソースからのビルド

make build          # current platform
make release        # cross-compile for all platforms into dist/

Go 1.25 以降が必要です。

CLI コマンド

MCP サーバーとしての実行に加えて、mail-shadow-mcp は、AI エージェントを使わずに手動操作、スクリプト作成、デバッグを行う際に便利な CLI コマンドをいくつか提供します。

1 回限りの同期を実行する（新着メールをローカルデータベースに取得して終了します）：

./mail-shadow-mcp sync

ローカルデータベースを照会する（出力は改行区切りの JSON で、jq のパイプラインに適しています）：

# Search by subject and body keyword
./mail-shadow-mcp query --subject "invoice" --body "Q1"

# Full-text search with attachment filter
./mail-shadow-mcp query -q "budget" --attachments only

# Most recent emails, paginated
./mail-shadow-mcp query --recent --limit 10 --offset 10

メール ID（形式は account:folder:uid）を指定して、添付ファイルをダウンロードする：

./mail-shadow-mcp attachments --id "[email protected]:INBOX:42"

---

ライセンス

Apache 2.0 — 詳細は LICENSE を参照してください。
Copyright (c) 2026 Benjamin Kaiser.