IMAP Mail

imap-mcp

AI アシスタント（例：Claude Desktop）にIMAP メールボックスの読み取りアクセスと下書きの作成機能を提供する、小規模な MCP サーバーです。Raspberry Pi 上で Hetzner のメールボックスと iCloud アカウントを使うために作成しましたが、IMAPS（ポート 993）に対応する任意の IMAP サーバーで動作します。

ステータス： 個人プロジェクトであり、現状のまま公開しています。信頼できるホームネットワークでの使用を想定しており、インターネットに公開する用途ではありません。セキュリティとSECURITY.mdを参照してください。

機能

ツール： list_accounts、list_folders、list_messages、search_messages、read_message、mark_read、create_draft。各ツールにはaccountパラメーターがあります。省略した場合は、設定済みの最初のアカウントが使われます。

• 読み取りは読み取り専用です。メッセージはBODY.PEEKで取得され、デフォルトでは既読にしたり、移動したり、削除したりすることはありません。
• 既存のメッセージへの書き込みは、mark_readまたは有効にした場合のread_message自体が設定する\Seenフラグのみです。既読状態を参照してください。
• メールの送信はできない仕様です。 create_draftは下書きフォルダーに下書きを保存します。内容を確認し、メールクライアントからご自身で送信してください。
• 下書きには、設定した1つのフォルダー（デフォルトでは無効）の添付ファイル（PDF、PNG、JPEG）を追加できます。添付ファイルを参照してください。
• 差出人には、アカウントのアドレスと設定済みのエイリアス（*@example.comのようなワイルドカードを使用できます）のみを指定できます。返信の場合、元のメールの宛先アドレスが自動的に選択されます。
• 読み込まれるメッセージは最大 2 MB です。メールが途中で切り詰められた場合、read_messageはmessage_truncatedを報告します。
• アカウントごとに1つの IMAP 接続を呼び出し間で再利用します。
• メールの内容は信頼できないデータとして扱われます（サーバーの指示とセキュリティを参照してください）。

要件

• Python 3.10+
• 必要に応じてアプリパスワードを設定した IMAP アカウント（iCloud、Gmail など）
• サーバー本体にはmcpとuvicornが必要です（requirements.txtを参照）。メール処理には標準ライブラリのみを使用します。

1. インストール

git clone https://github.com/<you>/imap-mcp.git
cd imap-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp config.env.example config.env
chmod 600 config.env
$EDITOR config.env          # user, password, aliases

.venv/bin/python -m unittest discover -s tests   # offline tests
.venv/bin/python server.py --check                # test the real IMAP connections

--checkはアカウントごとに1行を出力します。出力例： OK [hetzner] [email protected] @ mail.your-server.de, Drafts: INBOX.Drafts, Senders: …

2a. SSH 経由で接続（stdio、推奨）

クライアントは必要に応じて SSH 経由でサーバーを起動します。開放ポートもトークンも不要で、SSH によって暗号化されます。パスフレーズの入力を求めないキーを使用してください（ssh -o BatchMode=yes host echo okが動作する必要があります）。claude_desktop_config.jsonの設定例：

{
  "mcpServers": {
    "mail": {
      "command": "ssh",
      "args": [
        "-T", "-o", "BatchMode=yes", "-o", "ServerAliveInterval=30",
        "user@your-host",
        "/path/to/imap-mcp/.venv/bin/python",
        "/path/to/imap-mcp/server.py"
      ]
    }
  }
}

2b. 代替手段：LAN 上の HTTP サービス

複数のマシンからサーバーを使う場合に便利です。

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'   # generate a token
# in config.env: MCP_AUTH_TOKEN=<token>

scripts/make-cert.sh        # self-signed certificate for this host
# in config.env:
# TLS_CERT=/path/to/imap-mcp/certs/server.crt
# TLS_KEY=/path/to/imap-mcp/certs/server.key

sudo cp imap-mcp.service /etc/systemd/system/    # adjust User= and the paths first
sudo systemctl daemon-reload
sudo systemctl enable --now imap-mcp

エンドポイントはhttps://<host>:8765/mcpで、Authorization: Bearer <token>が必要です。--hostを指定しない場合、サーバーは127.0.0.1のみで待ち受けます。systemd ユニットは--host 0.0.0.0（すべてのインターフェース）を渡すため、必要に応じて LAN のアドレスに変更してください。通常の HTTP リクエスト以外（WebSocket など）は拒否されます。TLS_CERT/TLS_KEYがない場合、サーバーは平文のまま動作を続け、警告をログに記録します。証明書の有効期間は 730 日です。有効期間の終了後にmake-cert.shを再実行し、証明書を再配布してください。

stdio のみを話すクライアントでは、mcp-remoteブリッジを使用できます（Node.js が必要です）。自己署名証明書を Node に信頼させる必要があるため、クライアントマシン上にあるserver.crtのコピーをNODE_EXTRA_CA_CERTSに指定してください。

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<host>:8765/mcp",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <token>",
               "NODE_EXTRA_CA_CERTS": "/path/on/the/client/server.crt" }
    }
  }
}

Claude の設定にあるカスタムコネクターは、Anthropic のクラウドから接続するため、LAN アドレスでは動作しません。

2c. 代替方法：Docker（ローカル stdio）

amd64 および arm64 向けのコンテナイメージが ghcr.io/buzzer/imap-mcp で公開されています。このサーバーは MCP registry に io.github.buzzer/imap-mcp として登録されています。クライアントは必要に応じてコンテナを起動し、環境変数として設定を渡します。

{
  "mcpServers": {
    "mail": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "IMAP_HOST", "-e", "MAIL_USER", "-e", "MAIL_PASSWORD",
               "ghcr.io/buzzer/imap-mcp:latest"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "MAIL_USER": "[email protected]",
        "MAIL_PASSWORD": "app-password"
      }
    }
  }
}

Configuration にあるすべてのキーを同じ方法で渡せます。複数のアカウントを使う場合は、設定ファイルをマウントすると便利です。 -v /path/to/config.env:/config.env:ro -e MAIL_MCP_CONFIG=/config.env。コンテナは UID 10001 で実行されるため、このユーザーがファイルを読み取れる必要があります。添付ファイルを使う場合は、フォルダーを読み取り専用でマウントし、ATTACHMENT_DIR にコンテナ内のパスを設定してください。

設定

すべてのキーについては config.env.example を参照してください（MAIL_USER、MAIL_PASSWORD、MAIL_ADDRESS、 MAIL_FROM_NAME、MAIL_ALIASES、IMAP_HOST、IMAP_PORT、IMAP_TIMEOUT、 DRAFTS_FOLDER、ATTACHMENT_DIR、ATTACHMENT_MAX_BYTES、ATTACHMENT_MAX_TOTAL_BYTES、 ATTACHMENT_MAX_COUNT、MARK_READ_ON_READ、BCC_SELF、ACCOUNTS、ACCOUNT_NAME、MCP_AUTH_TOKEN、 TLS_CERT、TLS_KEY）。ATTACHMENT_MAX_COUNT までのアカウントキーには、追加アカウント用に <NAME>_ を接頭辞として付けられます。残りのキーはグローバル設定です。すべてのキーは環境変数としても設定できます。別の設定ファイルを選択するには、MAIL_MCP_CONFIG または --config を使います。

追加アカウント：iCloud

ACCOUNTS=hetzner,icloud
ICLOUD_MAIL_USER=first.last                # login, usually the part before @icloud.com
[email protected]
ICLOUD_MAIL_PASSWORD=abcd-efgh-ijkl-mnop   # app-specific password

パスワードには Apple ID のパスワードではなく、account.apple.com で発行したアプリ用パスワードを使います （「サインインとセキュリティ」→「アプリ用パスワード」）。 アカウント名が icloud の場合は imap.mail.me.com:993、hetzner の場合は mail.your-server.de:993 が事前設定されています。それ以外のアカウント名には <NAME>_IMAP_HOST が必要です。サーバーがホストを推測することはないため、パスワードが誤ったプロバイダーに送信されることはありません。

既読状態

ローカルのメールクライアントでアシスタントがすでに確認したメールが分かるように、read_message は返す各メッセージに \Seen フラグを設定できます。

• config.env で MARK_READ_ON_READ=true にすると、すべてのアカウントで有効になります（デフォルトではオフのグローバル設定です）。呼び出しごと、またはアカウントごとの設定はありません。
• これを行うのは read_message だけです。メールの一覧表示と検索ではヘッダーのみを表示し、フラグは変更しません。別の方法で処理したメッセージには、引き続き mark_read を利用できます。
• 結果には unread（読み取り前の状態）と marked_read が含まれます。フラグを設定できない場合もメッセージは返され、marked_read は false になります。
• 設定されるのは \Seen だけです。すでに既読のメッセージは変更されません。

自分への Bcc

config.env で BCC_SELF=true にすると（デフォルトではオフの、すべてのアカウントに適用される設定です）、create_draft は下書きの送信者アドレスを Bcc に追加するため、送信済みコピーもそのメールボックスに届きます。追加されるのは実際に送信者として使われるアドレスです（アカウントアドレスまたはエイリアス。from_address を参照）。すでに To、Cc、または Bcc に含まれている場合、重複して追加されることはありません。結果には最終的な bcc が表示され、list_accounts は bcc_self を報告します。

添付ファイル

create_draft は、ATTACHMENT_DIR からの相対パスで指定するファイルパスのリスト attachments を受け付けます。この機能は config.env でキーを設定するまで無効です（list_accounts はアカウントごとに attachments_enabled を表示します）。以下のルールはすべてサーバー側で適用されます。

• 使用できるのは .pdf、.png、.jpg、.jpeg のみです。ファイルの内容は対応するマジックバイトで始まる必要があります（拡張子を変更したファイルは拒否されます）。
• ATTACHMENT_DIR 内のファイルのみ使用できます。絶対パス、..、シンボリックリンク、隠しファイルや隠しフォルダー（.env、.ssh など）は拒否されます。
• ファイル数は最大 ATTACHMENT_MAX_COUNT 個（デフォルトは 5 個）、各ファイルは最大 ATTACHMENT_MAX_BYTES（デフォルトは 10 MB）、合計で最大 ATTACHMENT_MAX_TOTAL_BYTES（デフォルトは 15 MB）です。
• すべての添付ファイルが条件を満たした場合にのみ、下書きが保存されます。モデルに渡されるのはファイル名のみで、ファイルの内容は渡されません。

推奨される設定

添付しても問題のないファイルだけを入れる、専用のフラットなフォルダーを使用してください。 その中のファイルはすべて、モデルが添付できます。

mkdir -p ~/mail-attachments
chmod 700 ~/mail-attachments

ATTACHMENT_DIR=/home/<user>/mail-attachments

• SSH 経由で stdio トランスポートを使用する場合、サーバーは SSH ユーザーとしてファイルを読み取ります。
• ツール呼び出しで指定するパスは、そのフォルダーからの相対パスです。例：invoice-2026-10.pdf または invoices/2026/invoice-2026-10.pdf。絶対パスは拒否されます。
• サーバーは読み取りのみを行います。ファイルは自分でそこに配置し（scp file.pdf host:mail-attachments/、 rsync、Syncthing または Samba 共有を使用）、ファイル名を指定して添付するようアシスタントに依頼してください。
• 複数のアカウントでは、次のようにプレフィックスを付けた別々のフォルダーを使用できます。 ICLOUD_ATTACHMENT_DIR=/home/<user>/mail-attachments-icloud。
• systemd ユニット（ProtectHome=read-only）では、サービスユーザーに読み取りアクセス権が必要です。 最も簡単なのは、/home の外部にフォルダーを作成する方法です。例：/opt/imap-mcp/attachments。
• 不要になったファイルは削除してください。

セキュリティ

• config.env にはメールボックスのパスワードが含まれています。chmod 600 を設定し、絶対にコミットしないでください（他のユーザーがファイルを読み取れる場合、サーバーが警告します）。
• メールの内容は信頼できないテキストです。サーバーの指示では、メールに含まれる依頼に従わないようモデルに伝えています。送信も削除もできないため、起こり得る被害は下書きの作成と、モデルへのメール内容の漏えいに限られます。
• HTML メールは、読者に見えないコンテンツ（display:none、hidden、opacity:0、折りたたまれたプレヘッダー、script／style／head）を含めずにテキストに変換されます。これにより、不可視のプロンプトインジェクションで最も一般的な隠し場所が取り除かれます。読めないだけのテキスト（白地に白文字や、子要素に設定された小さなフォント）は引き続き渡されるため、この保護はリスクを軽減するものであり、保証ではありません。
• 制御文字（CR/LF）を含む検索語は拒否されるため、追加の IMAP コマンドを注入できません。改行を含む受信者アドレスも拒否されます。
• HTTP トランスポートでは、レート制限のない単一の静的ベアラートークンを使用します。信頼できるネットワーク上で TLS を使用してのみ利用し、トークンが漏えいした場合はローテーションしてください。
• HTTP 認証の失敗はクライアント IP とともにログに記録されます。ツール呼び出しは、メールの内容を含めずに記録されます（アカウント、フォルダー、UID）。

既知の制限事項

• 下書きはプレーンテキストのみです。引用返信の帰属行 （「Am … schrieb …:」）と、件名のプレースホルダー「(kein Betreff)」はドイツ語です。
• 添付ファイルは 1 つのフォルダー内の PDF／PNG／JPEG に限られます。メッセージの移動や削除はできず、設定できるフラグは \Seen（mark_read 経由）のみです。
• Hetzner（Dovecot）および iCloud のみでテスト済みです。

開発

python -m unittest discover -s tests    # no network and no MCP SDK needed

リリース

サーバーは ghcr.io/buzzer/imap-mcp のコンテナーイメージとして配布され、MCP レジストリには io.github.buzzer/imap-mcp として登録されています。バージョンタグがプッシュされると、publish ワークフロー（.github/workflows/publish.yml）によって両方が更新されます。

1. server.json の 2 か所、version と packages[0].identifier の末尾にあるイメージタグに、新しいバージョンを設定します。
2. コミットしてから、タグを付けてプッシュします：git tag v0.3.0 && git push origin main v0.3.0。 タグと server.json の内容が一致しない場合、ワークフローは失敗します。
3. 結果を確認します： curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.buzzer/imap-mcp"

知っておくべきこと：

• レジストリにはメタデータのみが保存され、Dockerfile のイメージラベル io.modelcontextprotocol.server.name によって所有権が検証されます。この値は server.json の name と同じにする必要があります。
• ワークフローは GitHub OIDC を使ってレジストリにログインするため、シークレットやトークンは不要です。名前空間 io.github.buzzer は GitHub アカウントに紐付けられています。
• クライアントに表示する新しい設定キーは、config.env.example に加えて、server.json の environmentVariables にも記載する必要があります。
• mcp-publisher は、ワークフロー内でバージョンと SHA-256 を指定して固定されています（MCP_PUBLISHER_VERSION、MCP_PUBLISHER_SHA256）。更新するには、リリースにある registry_<version>_checksums.txt から mcp-publisher_linux_amd64.tar.gz のチェックサムを取得してください。
• server.json は mcp-publisher validate でローカルに検証できます。

ライセンス

MIT