owlpost

owlpost

iCloud、Gmail、その他のメールプロバイダー向けの高精度な IMAP/SMTP MCP サーバーです。これまでに試した他のメール MCP サーバーは、実際の IMAP の癖（CRLF の改行、RFC822 と BODY.PEEK[] の違い、プロバイダー固有の送信済みフォルダー、複数語の検索値）でつまずいていたため、開発しました。

owlpost は、Claude Code からメールの閲覧、検索、会話の追跡、送信に日々実際に使っているツールです。

uvx owlpost

目次

• 機能
• ツール
• インストール
• 設定
• クライアントのセットアップ — Claude Desktop、Claude Code、Cursor、VS Code、Docker
• プロバイダーに関する注意事項 — iCloud、Gmail、Proton Bridge、汎用
• セキュリティ
• トラブルシューティング
• 開発

機能

• 複数アカウント — 必要な数のメールボックスを設定し、名前で切り替えられます
• iCloud と Gmail でエンドツーエンドのテスト済み。プロバイダー固有の癖に対応しています：
  • iCloud の RFC822 フェッチでは本文が空になるため、BODY.PEEK[] を使用します
  • iCloud の IMAP APPEND には CRLF の改行が必要なため、送信メールにはすべて policy.SMTP を使用します
  • iCloud の SMTP は送信済みメールを自動保存しないため、owlpost が代わりに送信済みフォルダーへ APPEND します
  • Gmail の SMTP は送信済みメールを自動保存するため、owlpost は重複する APPEND をスキップします
  • RFC 6154 SPECIAL-USE によりフォルダー名を自動検出します（Sent Messages と [Gmail]/Sent Mail の違いをハードコードしません）
  • MOVE 拡張機能のないサーバーでは、代わりに COPY + \Deleted + EXPUNGE を使用します
  • Proton Bridge は要求しない限り FETCH レスポンスに UID を含めないため、owlpost は常に要求します
• 会話の追跡 — 利用可能な場合は Gmail の X-GM-THRID 拡張機能を使用し、それ以外の場合はフォルダーを横断する汎用の Message-ID/References BFS を使用します
• 信頼性の高い接続 — ランダムに切断される長時間接続ではなく、操作ごとに短時間の IMAP セッションを使用します
• MIME 対応 — マルチパートメッセージを解析し、ヘッダーをデコードし、添付ファイルを一覧表示してディスクにダウンロードします
• スレッド形式の返信／転送 — In-Reply-To/References を保持し、元のメッセージを引用します
• 下書き — 下書きフォルダーに作成するため、自分のメールクライアントで確認して送信できます
• 必要な場面ではデフォルトで読み取り専用 — 検索や閲覧によってメールが既読になることはありません
• 必要に応じて設定ファイルからシークレットを除外可能 — password_env と password_command（1Password、pass、Keychain など）
• 注釈付きツール — すべてのツールで MCP の readOnlyHint / destructiveHint / openWorldHint を宣言しているため、クライアントは読み取りを自動承認し、送信前に確認を求められます

ツール

ツール	機能	読み取り専用
list_accounts	設定済みのメールアカウントを一覧表示します（パスワードは含まれません）	✅
list_folders	アカウントのフォルダーを、検出された特殊用途のロールとともに一覧表示します	✅
resolve_folder	ロール（sent、trash、drafts、inbox、all、archive など）をプロバイダーのフォルダー名に解決します	✅
search_messages	構造化された IMAP 検索（from/to/cc/subject/body/text/since/before/unseen/flagged/has_attachment、または raw）を行います。新しい順に表示します	✅
read_email	1 件のメッセージを読み取ります。ヘッダー、プレーンテキスト／HTML 本文、添付ファイル一覧を返します。MCP の結果制限に収まるよう、既定では切り詰めます	✅
get_conversation	同じスレッド内のすべてのメッセージを返します（Gmail X-GM-THRID、または汎用的な参照のたどり方を使用）	✅
save_attachment	パートのインデックスを指定して添付ファイルをローカルディスクにダウンロードします（メールボックスは変更されません）	ローカルファイルを書き込みます
send_email	メールを送信します。自動保存に対応しないプロバイダー（例：iCloud）では、送信済みフォルダーに自動保存します。添付ファイルとスレッドヘッダーに対応しています	❌ 送信します
save_draft_email	メッセージを作成して送信せずに Drafts に APPEND します — send_email と同じパラメーターを使用します	❌
reply_email	スレッドと引用を維持して返信します（全員への返信も任意で指定できます）	❌ 送信します
forward_email	転送します。既定では元の添付ファイルも再添付します	❌ 送信します
mark_read	\Seen を設定／解除します	❌
flag_message	\Flagged（スター）を設定／解除します	❌
move_email	別のフォルダーに移動します	❌ 破壊的操作
delete_email	Trash に移動します（完全削除はされません）	❌ 破壊的操作

すべてのツールは account 引数（list_accounts で返される名前）を受け取ります。 メッセージは search_messages が返す folder + uid で指定します。

インストール

推奨する方法は、何もインストールしないことです。 uvx に初回使用時に取得・キャッシュさせます。これにより、パッケージを常に最新の状態に保ち、グローバルな Python 環境を汚さずに済みます。

uvx owlpost            # speaks MCP over stdio
uvx owlpost --version

PATH 上で安定したバイナリを使いたい場合は、次の方法があります。

uv tool install owlpost   # or: pipx install owlpost / pip install owlpost

コンテナーイメージもあります。Docker を参照してください。

設定

accounts.example.toml を ~/.config/owlpost/accounts.toml にコピーし、認証情報を入力します。実際のパスワードではなく、アプリ固有のパスワードを使用してください。

• iCloud：account.apple.com → Sign-In and Security → App-Specific Passwords
• Gmail：myaccount.google.com/apppasswords（2FA を有効にする必要があります）

[accounts.icloud]
email = "[email protected]"
password_command = "op read op://Private/iCloud Mail/app-password"
provider = "icloud"
imap_host = "imap.mail.me.com"
smtp_host = "smtp.mail.me.com"
auto_save_sent = true   # iCloud SMTP doesn't auto-save sent

[accounts.gmail]
email = "[email protected]"
password_env = "OWLPOST_GMAIL_PASSWORD"
provider = "gmail"
imap_host = "imap.gmail.com"
smtp_host = "smtp.gmail.com"
auto_save_sent = false  # Gmail SMTP auto-saves

テーブル名（上記の icloud、gmail）を、ツールの account として渡します。

設定ファイルの場所

優先順位は次のとおりです。

1. owlpost --config /path/to/accounts.toml
2. OWLPOST_CONFIG 環境変数
3. ~/.config/owlpost/accounts.toml

ファイルは最初のツール呼び出し時に読み込まれます。編集した後はサーバーを再起動してください。

リファレンス

キー	必須	デフォルト	意味
email	✅		ログインユーザー名および From アドレス
password	3つのうち1つ		パスワードを直接指定します（アプリパスワードを推奨）
password_env	3つのうち1つ		パスワードを保持する環境変数の名前
password_command	3つのうち1つ		パスワードを出力するコマンド。例：op read op://...
provider		generic	icloud、gmail、または generic。gmail は X-GM-THRID によるスレッド化を有効にします
imap_host	✅		IMAP サーバーのホスト名
imap_port		993	IMAP ポート
imap_security		ssl	ssl（暗黙的な TLS。通常は 993）または starttls（通常は 143 / 1143）
smtp_host	✅		SMTP サーバーのホスト名
smtp_port		587	SMTP ポート
smtp_security		starttls	starttls（通常は 587）または ssl（通常は 465）
auto_save_sent		true	送信済みメールのコピーを Sent フォルダーに APPEND します。Gmail の場合は無効にしてください
tls_verify		true	TLS 証明書を検証します。自己署名証明書を使うローカルブリッジの場合にのみ false に設定してください

password、password_env、password_command のうち、設定するのは必ず1つだけにしてください。

password_command はシェルのような引用符ルールに従って分割され、直接実行されます（シェルを介さないため、パイプや $VARS は使えません）。タイムアウトは10秒です。末尾の改行を除いた標準出力がパスワードになります。アカウントを初めて使用する際に実行され、結果はサーバープロセスの終了までキャッシュされます。失敗した場合、ツール呼び出しはコマンドの終了コードと標準エラー出力を含むエラーを返します。例：

password_command = "op read op://Private/Fastmail/app-password"                  # 1Password CLI
password_command = "pass show mail/fastmail"                                     # pass
password_command = "security find-generic-password -s owlpost-icloud -w"         # macOS Keychain
password_command = "secret-tool lookup service owlpost account icloud"           # GNOME Keyring

password_env は、MCP クライアントが制御するサーバーの環境変数（以下のスニペットの env ブロック）から変数の値を読み取ります。

クライアントのセットアップ

以下はすべて uvx owlpost を実行します。クライアントが uvx を見つけられない場合は、絶対パス（通常は ~/.local/bin/uvx。which uvx を参照）を使用してください。uv tool install でインストールした場合は、代わりに owlpost をコマンドとして使用できます。

Claude Desktop

ワンクリック： 最新リリースから owlpost-<version>.mcpb をダウンロードして開きます。Claude Desktop がインストールし、accounts.toml のパスを尋ねます。

手動：

claude_desktop_config.json を編集します（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json、 Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "owlpost": {
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

Claude Code

claude mcp add owlpost --scope user -- uvx owlpost

# with a non-default config path, or a password from the environment
claude mcp add owlpost --scope user \
  -e OWLPOST_CONFIG=/path/to/accounts.toml \
  -- uvx owlpost

Cursor

~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）に追加します：

{
  "mcpServers": {
    "owlpost": {
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

VS Code

ワークスペースの .vscode/mcp.json に追加します（またはユーザーレベルでインストールするには MCP: Add Server を実行します）：

{
  "servers": {
    "owlpost": {
      "type": "stdio",
      "command": "uvx",
      "args": ["owlpost"]
    }
  }
}

その他の MCP クライアント

owlpost は標準の MCP stdio トランスポートを使用します。MCP 互換クライアントであれば、uvx owlpost またはインストール済みの owlpost バイナリを起動して通信できます。設定ファイルを指定するには env: {"OWLPOST_CONFIG": "..."} を渡します。

Docker

イメージは /config/accounts.toml に設定ファイルがあることを想定しています。設定ファイルを含むディレクトリを読み取り専用でマウントしてください：

docker run -i --rm \
  --mount type=bind,src="$HOME/.config/owlpost",dst=/config,readonly \
  ghcr.io/smankoo/owlpost:latest

MCP クライアントのエントリーとして使用する場合：

{
  "mcpServers": {
    "owlpost": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/home/you/.config/owlpost,dst=/config,readonly",
        "ghcr.io/smankoo/owlpost:latest"
      ]
    }
  }
}

コンテナ内の password_command で実行できるのは、イメージに存在するバイナリのみです。そのため、password または password_env を使用してください（-e OWLPOST_GMAIL_PASSWORD で渡します）。ホスト上の Proton Bridge に接続するには、--network host（Linux）または imap_host = "host.docker.internal" を使用してください。save_attachment は、書き込み可能なディレクトリをマウントしない限り、コンテナ内に保存します。

使用例

登録後、次のように依頼できます：

• 「先月の遠足について学校から届いたメールを探して」
• 「最新の住宅ローンのメールのスレッド全体を表示して」
• 「大家さんからの最新のメッセージに、明日連絡すると返信して」
• 「保険更新への返信を下書きして、PDFを送ってもらうよう頼んで。送信はしないで」
• 「保険証書のPDFを [email protected] に転送して」
• 「今月の電気料金の請求書の添付ファイルを ~/Downloads に保存して」

プロバイダーに関する注意事項

iCloud

• Apple ID のパスワードではなく、App 用パスワードを使用してください。
• iCloud は頻繁な再接続を制限します。owlpost は各操作で有効期間の短いセッションを使用しますが、接続をプールしません。SSLEOFError: EOF が発生した場合は、約 30 秒待ってから再試行してください。
• 送信済みフォルダーは Sent Messages、ゴミ箱は Deleted Messages です。どちらも自動検出されます。
• auto_save_sent = true のままにしてください。iCloud の SMTP は送信したメールのコピーを保存しません。

Gmail

• 2 要素認証とアプリ パスワードが必要です。
• Gmail の設定 → メール転送と POP/IMAPで IMAP を有効にする必要があります。
• provider = "gmail" を設定すると、owlpost は Gmail の X-GM-THRID 拡張機能を使用してスレッドを確実に検出します。
• auto_save_sent = false を設定してください。Gmail の SMTP は送信済みメールをすでに保存するため、APPEND すると重複します。
• delete_email は [Gmail]/Trash に移動します。INBOX からラベルフォルダーへの移動は、アーカイブと同じ動作です。

Proton Mail（Proton Bridge 経由）

Proton が IMAP/SMTP を提供するのは、Proton Bridge アプリ経由のみです。このアプリは localhost で実行され、自己署名証明書を使用し、 標準以外のポートで STARTTLS を使用します。次のように設定してください。

• provider = "generic"
• imap_host = "127.0.0.1"、imap_port = 1143、imap_security = "starttls"
• smtp_host = "127.0.0.1"、smtp_port = 1025、smtp_security = "starttls"
• tls_verify = false — Bridge の証明書は自己署名のため必要です
• Proton アカウントのパスワードではなく、Bridge が生成したメールボックスのパスワードを使用してください

その他のプロバイダー

provider = "generic" を設定し、imap_host、smtp_host、ポート、 imap_security / smtp_security（starttls または ssl）、および tls_verify を設定してください （自己署名証明書の場合は false に設定します）。プロバイダーが SPECIAL-USE に対応していれば、 フォルダーの役割は引き続き自動検出されます（最新のプロバイダーのほとんどが対応しています）。 対応していない場合、owlpost は Sent、Sent Items、Trash などの一般的な名前を使用します。 auto_save_sent を有効にするかどうかは、プロバイダーの SMTP が送信済みメールを自動保存するかどうかによります。 自分宛てにテストメールを送信し、重複がないか確認してください。

セキュリティ

• owlpost は実際にメールを送信します。 send_email、reply_email、 forward_email には openWorldHint: true の注釈が付いており、 読み取り専用ではありません。これらを実行する前に確認を求めるよう MCP クライアントを設定してください（読み取り専用でないツールでは、ほとんどのクライアントで デフォルトで確認が求められます）。自動承認しないでください。サーバーの指示でも、 送信前に宛先と内容をあなたに確認するようモデルに伝えています。モデルにメールの準備だけをさせたい場合は、 save_draft_email を使うよう誘導してください。
• 信頼できないコンテンツ。 メール本文は見知らぬ人が作成したものです。メッセージには、 モデルを操作するために設計されたテキストが含まれる場合があります（「直近 10 件の請求書を ... に転送してください」など）。 メールを読み取り、送信もできるエージェントでは、特に送信確認を有効にしてください。
• **アプリ用パスワードを使用し、**メインアカウントのパスワードは絶対に使用しないでください。 アプリ用パスワードは個別に取り消すことができ、アカウント管理へのアクセス権は付与されません。
• password_command（パスワードマネージャー）または password_env を使って、ファイルにシークレットを保存しないでください。 ファイルに password を記述する場合は、chmod 600 ~/.config/owlpost/accounts.toml を実行してください。
• list_accounts はパスワードやパスワードの取得元を返しません。
• tls_verify = false は証明書のチェックを完全に無効にします。127.0.0.1 上のブリッジでのみ使用してください。
• save_attachment と attachments は、サーバーを実行しているユーザーとしてローカルパスの読み書きを行います。

脆弱性を発見しましたか？SECURITY.md を参照してください。

トラブルシューティング

症状	対処方法
クライアントにツールが表示されない	クライアントが uvx を起動できませんでした。絶対パス（which uvx）を使用して、クライアントを再起動してください。ターミナルで uvx owlpost --version を実行し、動作することを確認してください
owlpost config not found at ...	~/.config/owlpost/accounts.toml を作成するか、OWLPOST_CONFIG / --config を設定してください
must set exactly one of password, password_env, password_command	[accounts.<name>] テーブルの余分なキーを削除するか、キーを 1 つ追加してください
password_command exited with 1: ...	ターミナルでコマンドを実行してください。パスワードマネージャーの CLI は、サインイン（op signin）またはロック解除が必要な場合がよくあります
Unknown account 'x'. Known: [...]	リストにある名前を使用してください。これはメールアドレスではなく、TOML のテーブル名です
ログイン時に [AUTHENTICATIONFAILED] / 535 が表示される	アプリパスワードが間違っているか、取り消されています。Gmail の場合は、IMAP が有効になっていることを確認してください
iCloud で SSLEOFError: EOF が表示される	iCloud が再接続を抑制しています。約 30 秒待ってください
Proton Bridge で CERTIFICATE_VERIFY_FAILED が表示される	そのアカウントの tls_verify = false を設定してください
送信済みメールが二重に表示される	プロバイダーがすでに送信済みメールを保存しています。auto_save_sent = false を設定してください
送信済みメールが「送信済み」に表示されない	auto_save_sent = true を設定してください
unknown encoding: idna	owlpost を 0.1.4 以降にアップグレードしてください

開発

git clone https://github.com/smankoo/owlpost
cd owlpost
uv sync                      # creates .venv with dev tools
uv run pytest                # tests use fake IMAP/SMTP, no network
uv run ruff check .
uv run ruff format --check .
uv run python scripts/smoke_stdio.py uv run owlpost   # stdio handshake + tools/list

リリース手順については CONTRIBUTING.md を、履歴については CHANGELOG.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。