Mail-MCP

Mail-MCP

Claude（Claude Desktop、Cowork、Claude Code、または任意の MCP クライアント）が Microsoft Graph を通じて個人用の Outlook.com／Hotmail／Live メールボックスを操作できる、小規模で目的を絞ったMCPサーバーです。メールの閲覧と検索、フォルダーへの振り分け、削除、そしてニュースレターの配信停止ができます。

AI アシスタントを使ってあふれかえった個人用受信トレイを安全に整理することだけを目的に作られています。

ツール

mail_ で始まる9つのツール：

ツール	機能
mail_list_folders	合計数／未読数付きのフォルダーツリー
mail_create_folder	フォルダーを作成（冪等）
mail_search	メッセージの一覧表示／検索（送信者、日付範囲、未読、全文）、ページネーション対応
mail_get_message	1件のメッセージ全文と検出された配信停止方法
mail_senders_summary	フォルダー全体を送信者ごとに集計：件数、最新のメッセージ、利用可能な配信停止方法
mail_move	最大500件のメッセージをフォルダーに移動
mail_delete	デフォルトでは「削除済みアイテム」に移動。完全に削除するには permanent: true を指定
mail_bulk_by_sender	特定の送信者からの全メッセージを移動または削除（dryRun 対応）
mail_unsubscribe	RFC 8058 のワンクリック POST → mailto: メール → それ以外の場合はアシスタントがブラウザーで開く URL

設計上の選択：

• デフォルトで安全です。 削除したメールは「削除済みアイテム」に移動します（Outlook で確認・復元できます）。完全削除には明示的なフラグが必要です。一括操作は dryRun に対応しています。
• 大容量メールボックスでも効率的です。 mail_senders_summary は数千件のメッセージを数秒でスキャンします（1,000件単位のページ、最小限の $select）。さらに、上位の送信者についてのみ $batch でヘッダーを取得します。
• 汎用の送信ツールはありません。 Mail.Send 権限は、mailto: の配信停止リクエストの送信にのみ使用されます。
• 各ツールには厳格な入力スキーマ、出力スキーマ、MCP アノテーション（readOnlyHint、destructiveHint など）が付属しているため、ホストは読み取り専用の呼び出しを自動承認できます。

要件

• Node.js 22 以降。
• 個人用 Microsoft アカウント（outlook.com、hotmail.com、live.com、msn.com）。
• 無料の Microsoft Entra アプリ登録（所要時間5分、以下を参照）。個人用アカウントでは2024年9月にパスワードベースの IMAP が無効化されたため、サポートされている方法は OAuth アプリのみです。

1. Microsoft Entra にアプリを登録する（初回のみ、無料）

パブリッククライアントアプリには Azure サブスクリプションは必要ありません。

1. https://entra.microsoft.com にアクセスし、個人用 Microsoft アカウントでサインインします。
2. Identity → Applications → App registrations → New registration を選択します。
3. 次の項目を入力します。
   • Name：Mail-MCP
   • Supported account types：Personal Microsoft accounts only
   • Redirect URI：プラットフォームに Mobile and desktop applications を選択し、値に http://localhost を指定します。
4. Register をクリックし、Application (client) ID（xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）をコピーします。
5. Authentication で、http://localhost が「Mobile and desktop applications」に表示されていることと、Allow public client flows が Yes になっていることを確認します。
6. API permissions で、Microsoft Graph の 委任された アクセス許可として Mail.ReadWrite、Mail.Send、User.Read、offline_access を追加します。管理者の同意は必要ありません。初回サインイン時に同意します。

クライアントシークレットは作成されません。このサーバーは、PKCE を使用した認可コードフローを使うパブリッククライアントです。

2. サインインする

インストールは不要です。npx が npm からパッケージ（@rixtay/mail-mcp、インストールされるコマンドは mail-mcp）を取得します。

MAIL_MCP_CLIENT_ID=<your-client-id> npx -y @rixtay/mail-mcp login

または、クローンから実行します。

git clone https://github.com/Rixtayz/Mail-MCP.git
cd Mail-MCP
npm install && npm run build
MAIL_MCP_CLIENT_ID=<your-client-id> npm run login

login コマンドを実行すると、システムブラウザーが開き、Microsoft にサインインした後、トークンキャッシュが ~/.mail-mcp/token-cache.json に保存されます（ファイルモード 600）。トークンは、90 日間のローリング期間中、サイレントに更新されます。ツールが「Token expired」と返した場合は、同じコマンドをもう一度実行してください。

環境変数	用途
MAIL_MCP_CLIENT_ID	必須。 手順 1 の Application (client) ID
MAIL_MCP_CACHE_PATH	任意。トークンキャッシュの保存先

3. Claude Desktop / Cowork に接続する

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json を、Windows では %APPDATA%\Claude\claude_desktop_config.json を編集します。Settings → Developer → Edit Config からも開けます。

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "@rixtay/mail-mcp"],
      "env": {
        "MAIL_MCP_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

Claude Desktop が npx を見つけられない場合（シェルの PATH を引き継がないため）、代わりに絶対パスを使用します。"command": "/absolute/path/to/node"、"args": ["/absolute/path/to/Mail-MCP/dist/index.js"] のように指定してください。

Claude Desktop を完全に終了してから、もう一度起動します。ログは ~/Library/Logs/Claude/mcp-server-mail.log にあります。

Cowork がローカルの MCP サーバーを実行するのは、クラウドセッションではなくローカルセッションのみです。

4. Claude Code に接続する

claude mcp add --scope user --env MAIL_MCP_CLIENT_ID=<your-client-id> --transport stdio mail -- npx -y @rixtay/mail-mcp

5. プロンプトの例

• 「受信トレイの送信者を要約して、ニュースレターに目印を付けてください。」
• 「6 か月間開いていないニュースレターの配信をすべて解除し、そのメッセージを削除済みアイテムに移動してください。」
• 「Invoices フォルダーを作成して、[email protected] からのメールをすべて移動してください。」
• 「銀行からの最新メールを表示してください。」

一般的な流れ：mail_senders_summary → アシスタントがリストを提案し、ユーザーが確認 → ニュースレターごとに mail_unsubscribe(lastMessageId) を実行（回答が method: "browser" の場合、アシスタントがブラウザーで URL を開き、そこで処理を完了します）→ mail_bulk_by_sender(action: "delete")。

開発

npm test          # vitest: header parsing, Graph retry/batch/pagination, service with a mocked Graph
npm run typecheck
npm run inspect   # MCP Inspector against dist/index.js

構成：

src/index.ts          CLI entry point: `mail-mcp` serves stdio, `mail-mcp login` signs in
src/login.ts          interactive sign-in flow
src/server.ts         builds the McpServer and registers the tools
src/auth.ts           MSAL public client, file-based token cache
src/graph.ts          Graph client: bearer auth, 429/503 retry, pagination, $batch in chunks of 20
src/mail.ts           business logic (folders, search, sender summary, move/delete, unsubscribe cascade)
src/unsubscribe.ts    List-Unsubscribe / List-Unsubscribe-Post parsing, RFC 8058 one-click POST
src/tools/*.ts        tool definitions (zod v4 schemas, annotations)

技術スタック：@modelcontextprotocol/server v2、zod v4、@azure/msal-node v6、html-to-text。

知っておくと便利なこと

• メッセージ ID は、メッセージのフォルダーが変わるたびに変わります。 mail_move と mail_delete は、変更前 → 変更後の ID 対応表を返します。
• 通常の削除は、削除済みアイテムへの移動です。Graph 独自の DELETE ではアイテムが回復可能なアイテムに移動し、Outlook では表示されないため、意図的に使用していません。
• Microsoft は Outlook に対し、メールボックスあたり 10 分間に 10,000 件、同時に 4 件までのリクエスト制限を設けています。バッチは順次処理され、429 が返された場合は再試行されます。
• query（全文検索）を使った mail_search は、ほかのフィルターと組み合わせられません（Graph の制限）。また、取得結果は数百件程度が上限です。
• 配信解除が実際に反映されるかどうかは、送信者次第です。ワンクリック方式と mailto: はリクエストを送信し、残りの処理はアシスタントのブラウザーが行います。
• authority は login.microsoftonline.com/consumers です。common を指定すると、個人アカウントの更新トークンは初回の更新後に拒否されます。

コントリビューション

バグ報告、修正、目的を絞った新しいツールを歓迎します。CONTRIBUTING.mdをご覧ください。実際のメール内容、アドレス、トークンを課題に貼り付けないでください。サーバーがメールやトークンを漏えいさせる可能性がある、または依頼されていない操作を行う可能性があることを発見した場合は、SECURITY.mdに記載されている方法で非公開で報告してください。

リリース履歴：CHANGELOG.md。

ライセンス

MIT