yahoo-mail-mcp

yahoo-mail-mcp

Yahoo API キーを必要とせず、通常の IMAP 経由で Claude から Yahoo Mail アカウントのメールを読み取り、検索、整理、クリーンアップできます。

LLM が IMAP 経由で Yahoo Mail アカウントのメールを読み取り、検索、移動、削除できる MCP（Model Context Protocol）サーバーです。

公開されるツール：list_folders、create_folder、list_emails、search_emails、 read_email、get_attachment、move_email、delete_email、mark_email。

各ツールは短時間だけ IMAP 接続を開いて処理を行い、接続を閉じます。 削除時は、IMAP の special-use フラグで検出した（名前をハードコードしていない）ゴミ箱への移動がデフォルトです。完全に削除するには、呼び出し元が明示的に permanent=True を渡す必要があります。フォルダー全体を削除または完全消去できるツールはありません。UID を指定した単一メッセージのみが対象です。

1. Yahoo アカウントで IMAP を有効にする

ほとんどの Yahoo Mail アカウントでは、IMAP アクセスはデフォルトで有効です。メールクライアントが接続できない場合は、**Yahoo Mail → Settings → More Settings → Mailboxes → [アカウント] →「安全性の低いサインインを使用するアプリを許可する」**を確認してください。ただし、ここで必要な設定はこれではありません。これは従来のパスワード認証用です。現在の Yahoo では、代わりに アプリパスワードが必要です（以下を参照）。このアプリパスワードは、従来の設定のオン／オフにかかわらず機能します。それでも接続に問題がある場合は、Yahoo Account Security にサインインし、アカウントがロックされていないか、不審なアクティビティとしてフラグが付けられていないか確認してください。

2. Yahoo アプリパスワードを生成する

2 段階認証を有効にすると、Yahoo は通常のアカウントパスワードを使った IMAP ログインをブロックします（また、一般にアプリパスワードの使用を推奨しています）。生成方法は次のとおりです。

1. https://login.yahoo.com/account/security にアクセスします。
2. 2 段階認証がまだ有効でない場合は有効にします（アプリパスワードに必須です）。
3. **「アプリパスワードを生成」**を探します（「アプリパスワード」／「アプリパスワードを管理」の下にある場合もあります）。
4. 「その他のアプリ」を選び、yahoo-mail-mcp のような名前を付けて生成します。
5. 生成されたパスワード（通常はスペースなしの 16 文字）をコピーします。Yahoo で表示されるのは一度だけです。

実際のアカウントパスワードではなく、このアプリパスワードを YAHOO_APP_PASSWORD として使用してください。

3. 依存関係をインストールする

Python 3.10 以降が必要です。

cd yahoo-mail-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. 認証情報を設定する

cp .env.example .env

.env を編集して、次の項目を入力します。

[email protected]
YAHOO_APP_PASSWORD=your16charapppassword

.env はすでに .gitignore に含まれています。絶対にコミットしないでください。

5. 接続を確認する

サーバーを Claude に接続する前に、認証情報が機能することを確認してください。

python test_connection.py

ログインしてフォルダーを一覧表示し、受信トレイの最新メール 3 件を出力します。 アプリパスワードが出力されることはありません。

6. サーバーを実行する

python server.py

このサーバーは stdio 経由で MCP と通信します。単独で対話的に使用するための実行ではなく、MCP クライアント（Claude Desktop、Claude Code）によって起動されることを想定しています。

7. Claude Desktop / Claude Code に登録する

このプロジェクトの仮想環境にある Python と server.py を指定するエントリーを、MCP 設定に追加します。絶対パスを使用してください。

Claude Desktop（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "yahoo-mail": {
      "command": "/absolute/path/to/yahoo-mail-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/yahoo-mail-mcp/server.py"],
      "env": {
        "YAHOO_EMAIL": "[email protected]",
        "YAHOO_APP_PASSWORD": "your16charapppassword"
      }
    }
  }
}

Claude Code — CLI を使って同じサーバーを追加します。

claude mcp add yahoo-mail /absolute/path/to/yahoo-mail-mcp/.venv/bin/python /absolute/path/to/yahoo-mail-mcp/server.py

または、上記と同じ JSON 形式で、Claude Code の MCP 設定ファイルに直接追加します。

アプリパスワードを MCP 設定の env ブロックに記載したくない場合は、そこから env を省略し、代わりに server.py と同じ場所にある .env を使用できます。サーバーが python-dotenv 経由で自動的に読み込みます。

設定を編集した後、Claude Desktop / Claude Code を再起動して、新しいサーバーを読み込ませてください。

使用方法

登録したら、Claude に自然に話しかけるだけで、Claude が適切なツールを自動的に選択します。たとえば、次のように頼めます。

• 「未読メールを一覧表示して」
• 「2026-01-01 以降に [email protected] から届いたメールを検索して」
• 「契約について Sarah から届いたメールを読んで」
• 「請求書のメールに添付されているファイルをダウンロードして」
• 「Receipts という名前のフォルダーを作成して」
• 「このメールを Receipts フォルダーに移動して」
• 「このメールをゴミ箱に移動して」／「この迷惑メールを完全に削除して」
• 「このメールを既読にして」／「未読にして」
• 「このメールボックスにはどんなフォルダーがある？」

エージェントスキル

skills/yahoo-mail/SKILL.md は、これらのツールを安全に使用するタイミングと方法をエージェントに教える、任意のエージェントスキルです（既定ではソフト削除、一括変更の確認、メールの内容を信頼できないものとして扱う）。skills/yahoo-mail/ フォルダーを ~/.claude/skills/（またはプロジェクトの .claude/skills/）にコピーしてください。上記の MCP サーバーが登録されている必要があります。

ツールのリファレンス

ツール	用途	主なパラメーター
list_folders	特殊用途フラグ付きで、すべての IMAP フォルダー／ラベルを一覧表示します	(なし)
create_folder	フォルダーがまだ存在しない場合に作成します（冪等）	name
list_emails	フォルダー内の最近のメールを新しい順に一覧表示します	folder="INBOX"、limit=20、unread_only=False
search_emails	送信者／件名／日付範囲／未読でフォルダーを検索します（条件は AND で結合）	folder、sender、subject、since（YYYY-MM-DD）、before、unread_only、limit
read_email	全ヘッダーと本文（プレーンテキスト、または HTML を除去したもの）、および添付ファイル名を取得します	uid、folder="INBOX"
get_attachment	添付ファイル 1 件の生バイトデータを Base64 エンコードして取得します	uid、filename、folder="INBOX"
move_email	UID を指定して、1 件のメッセージをフォルダー間で移動します	uid、from_folder、to_folder
delete_email	メッセージを削除します。既定ではソフト削除（ゴミ箱）です	uid、folder="INBOX"、permanent=False
mark_email	既読（\Seen）フラグを設定／解除します	uid、folder="INBOX"、read=True

安全性に関する動作の注意事項

• delete_email(permanent=False)（既定）はメッセージをゴミ箱に移動するため、復元できます。permanent=True はただちに完全削除するため、呼び出し元が明示的に指定する必要があります。
• move_email と delete_email は、まずメッセージのエンベロープを取得して、そのメッセージが存在することを確認します。また、結果に件名と送信者を含めるため、適切なメールに対して操作したことを確認できます。
• すべての操作では IMAP UID でメッセージを指定します。UID はセッションをまたいで有効です（変動する可能性があるシーケンス番号は使用しません）。
• IMAP エラーは、生の例外／スタックトレースではなく、構造化された {"error": ..., "error_type": ...} 辞書として呼び出し元に返されます。

免責事項

これは独立した非公式プロジェクトです。Yahoo、Oath/Verizon Media、Anthropic とは提携、推奨、または後援の関係にありません。標準の IMAP プロトコルとアカウントに紐づくアプリパスワードを使用して Yahoo Mail と通信します。Yahoo API キーや OAuth は使用しません。このツールの使用には、Yahoo 独自の利用規約が適用されます。本ソフトウェアは現状有姿で提供され、保証はありません。LICENSE を参照してください。

貢献

課題やプルリクエストを歓迎します。CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。