Outlook Mail

Claude、Codex、その他あらゆる MCP クライアントが、Microsoft Graph API を通じて Outlook／Microsoft 365／Outlook.com のメールを読み取り、検索、送信、整理できる Model Context Protocol サーバーです。

---

🔭 概要

outlook-mcp は stdio を介してローカルで動作します。OAuth デバイスコードフロー（クライアントシークレットもリダイレクト URI も不要）でサインインし、更新トークンを OS のキーチェーン（または自分だけが読み取れるローカルファイル）に保存して、標準の fetch で Microsoft Graph と通信します。

✨ 機能

• 📂 フォルダーの閲覧、メッセージの一覧表示と検索（KQL）、本文のサニタイズ済みプレーンテキストでの読み取り
• 📎 添付ファイルの一覧表示と、安全な設定済みディレクトリへのダウンロード
• ✉️ メールの送信、下書きの作成、返信、全員に返信、転送（ローカル添付ファイルは最大 150 MB、3 MB 以上のファイルはチャンクでアップロード）
• 🗂️ メッセージの移動、既読／未読への変更、フラグ付け、削除を、1 件ずつ、または一括で実行（ids）
• 📰 ニュースレターの検索、配信登録解除、受信トレイルールによる不要な送信者のブロック
• 🔒 変更を伴うすべてのツールを削除する読み取り専用モード
• 🔁 スロットリング（429／503／504）時に Retry-After／指数バックオフを使って自動再試行
• 🧾 ログは stderr のみに出力し、トークンやメッセージ本文は記録しません

📋 要件

• Node.js 24（LTS）以降
• Microsoft アカウント（個人アカウントはすぐに利用できます。職場または学校のアカウントには独自の Azure アプリが必要です）

🚀 クイックスタート

ターミナルでのサインインも Azure の設定も不要です。Node.js 24 以降だけが必要です。

Claude Code

claude mcp add outlook --scope user -- npx -y @pepebits/outlook-mcp

Claude Desktop

claude_desktop_config.json に追加し、Claude Desktop を再起動します。

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@pepebits/outlook-mcp"]
    }
  }
}

Codex（OpenAI）

codex mcp add outlook -- npx -y @pepebits/outlook-mcp

または ~/.codex/config.toml に追加します（Codex CLI と IDE 拡張機能で共有されます）。

[mcp_servers.outlook]
command = "npx"
args = ["-y", "@pepebits/outlook-mcp"]
# env = { OUTLOOK_READ_ONLY = "true" }

Codex 内で /mcp を実行し、接続されていることを確認します。

その他の MCP クライアント

stdio MCP サーバーを起動できるクライアントであれば、どれでも利用できます。サーバーコマンドとして npx -y @pepebits/outlook-mcp を実行してください。

サインイン

アシスタントに 「Outlook にログインして」 と依頼します。login ツールから URL と一度限りのコードが返されるので、URL を開いてコードを入力し、承認してください。ターミナルを使う場合は、代わりに npx -y @pepebits/outlook-mcp auth を実行します。

デフォルトでは、サーバーは共有の outlook-mcp Azure アプリを使用します。このアプリは個人用 Microsoft アカウント（outlook.com、hotmail、live）に対応しています。同意画面に 未確認の発行元 の警告が表示されることがあります。当社のサーバーを経由してデータが送信されることはありません。サーバーはお使いのマシンから Microsoft Graph に直接通信し、トークンはローカルのトークンキャッシュに保存されます。職場または学校のアカウントを使う場合、または独自のアプリを使用する場合は、独自の Azure アプリを使用するをご覧ください。

⚙️ 設定（.env）

.env ファイルは任意です。変数はカレントディレクトリとパッケージディレクトリにある .env から読み込まれ、実際の環境変数が優先されます。MCP クライアントの env ブロックを介して渡すこともできます。例：claude mcp add outlook --scope user -e OUTLOOK_TENANT=organizations -e OUTLOOK_CLIENT_ID=your-client-id -- npx -y @pepebits/outlook-mcp

変数	デフォルト	説明
OUTLOOK_CLIENT_ID	shared outlook-mcp app	独自の Azure アプリ登録のアプリケーション（クライアント）ID（任意）。
OUTLOOK_TENANT	consumers	認証テナント：consumers（個人）、organizations（職場または学校）、common（両方）、またはテナント GUID。
OUTLOOK_SCOPES	User.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite offline_access	サインイン時に要求する、スペース区切りの委任 Graph スコープ。
OUTLOOK_TOKEN_STORE	auto	トークンキャッシュの保存先：auto（利用可能な場合は OS キーチェーン、そうでなければファイル）、keychain（キーチェーンがない場合は失敗）、または file。トークンの保存を参照してください。
OUTLOOK_TOKEN_CACHE	~/.config/outlook-mcp/token-cache.json	file ストア用のトークンキャッシュファイル（モード 0600）。キーチェーンエントリの識別にも使用されます。
OUTLOOK_READ_ONLY	false	true の場合、送信、移動、削除、フラグ付け、既読化のツールは登録されません。
OUTLOOK_DOWNLOAD_DIR	~/Downloads	添付ファイルを書き込める唯一のディレクトリ。
OUTLOOK_DEFAULT_TOP	20	一覧表示／検索ツールのデフォルトのページサイズ（1～100）。
OUTLOOK_MAX_BODY_CHARS	20000	get_message が返す本文の最大文字数。
OUTLOOK_GRAPH_BASE_URL	https://graph.microsoft.com/v1.0	Graph エンドポイント（各国のクラウドでは変更してください）。
LOG_LEVEL	info	debug、info、warn、error のいずれか（標準エラーに出力）。

🔐 認証

npx -y @pepebits/outlook-mcp auth      # device code sign-in; prints a URL and a code
npx -y @pepebits/outlook-mcp whoami    # silent token + GET /me
npx -y @pepebits/outlook-mcp logout    # removes accounts and deletes the token cache (keychain entry and file)

ターミナルを使わずにサインインすることもできます。アシスタントに 「Outlook にログインして」 と頼むだけです。

• 🔑 login は URL と一度限りのコードを返します。URL を開いてコードを入力し、承認すると、バックグラウンドでサインインが完了します。
• ✅ auth_status では、サインイン済み、待機中、サインアウト済みのいずれかを確認できます。
• 🚪 logout はキャッシュされたアカウントとトークンキャッシュ（キーチェーンエントリとファイル）を削除します。

Azure で権限を追加した後などに再度サインインするには、force: true を指定して login を使います。セッションがない、または有効期限が切れている場合、ツールは 「Not signed in or session expired. Call the login tool ...」 を返します。

🗝️ トークンの保存

更新トークンは、このサーバーが保持する情報の中で最も機密性の高いものです。そのため、デフォルト（OUTLOOK_TOKEN_STORE=auto）では通常のファイルではなく、オペレーティングシステムのキーチェーンに保存されます。ネイティブの npm 依存関係は使用せず、サーバーが OS のツールを直接呼び出します。

プラットフォーム	バックエンド	備考
macOS	security CLI 経由の Keychain	サービスは outlook-mcp、アカウントはキャッシュパスです。
Linux	secret-tool（libsecret）経由の Secret Service	secret-tool がインストールされ、キーリングが実行されている場合にのみ使用されます。それ以外の場合はファイルストアが使用されます。
Windows およびその他	ファイル	~/.config/outlook-mcp/token-cache.json、モードは 0600 です。

• 移行： キャッシュファイルが存在し、キーチェーンがまだ空の場合、ファイルの内容がキーチェーンにインポートされ、ファイルは削除されます。
• フォールバック： auto モードで実行時にキーチェーンを使用できない場合、サーバーはファイルにフォールバックし、警告をログに記録します。OUTLOOK_TOKEN_STORE=keychain の場合はフォールバックせず、失敗します。file の場合はキーチェーンにアクセスしません。
• プロセス一覧にシークレットが表示されません： Linux では、secret-tool は標準入力からシークレットを読み取ります。security add-generic-password ではパスワードをコマンドライン引数としてしか受け取れず（他のローカルプロセスから ps で確認できます）、macOS では代わりに security -i へ標準入力経由でコマンドを渡します。このインターフェースでは行が約 4 KB で切り詰められるため、キャッシュは base64 エンコードされ、いくつかの小さなキーチェーン項目（<account>#0、#1、…）に分けて保存されます。
• logout（ツールおよび CLI）は、キーチェーンの項目とファイルの両方を削除します。
• macOS では、別のバイナリから初めてアクセスすると Keychain の確認プロンプトが表示される場合があります。常に許可をクリックしてください。

🛠️ 独自の Azure アプリを使用する（任意）

デフォルトでは、outlook-mcp は共有の outlook-mcp Azure アプリを使用します。このアプリは個人用 Microsoft アカウントでのみ動作します。職場または学校のアカウントが必要な場合や、独自のアプリを使用したい場合は、アプリを登録してください。その後、OUTLOOK_CLIENT_ID（および下記の OUTLOOK_TENANT）を設定します。

手順

1. portal.azure.com を開き、Microsoft Entra ID -> アプリの登録 -> 新規登録に進みます。

2. 名前を付けます（例：outlook-mcp）。

3. サポートされているアカウントの種類で、次のいずれかを選択します。

   • 個人用 Microsoft アカウントのみ（Outlook.com、Hotmail、Live）、または
   • 任意の組織ディレクトリ内のアカウントと個人用 Microsoft アカウント（両方）。
   • 職場または学校のアカウントのみの場合は、組織向けのオプションを選択します。

4. リダイレクト URIは空のままにして、登録をクリックします。

5. 左側のメニューから管理 -> 認証 -> 設定タブに進み、パブリック クライアント フローを許可するをはいに設定して保存します。

6. 管理 -> API のアクセス許可に進みます。User.Readは既定で付与されています。アクセス許可の追加 -> Microsoft Graph -> 委任されたアクセス許可をクリックして、次のアクセス許可を追加します。

   • 📬 Mailグループを展開し、Mail.ReadWriteとMail.Sendにチェックを入れます。
   • ⚙️ MailboxSettingsグループを展開し、MailboxSettings.ReadWriteにチェックを入れます（受信トレイルールとblock_senderに必要です）。
   • 🔑 OpenId permissionsグループを展開し、offline_accessにチェックを入れます。

   次に、アクセス許可の追加をクリックします。個人用アカウントでは管理者の同意は不要です。

スコープ	用途
User.Read	サインインとwhoami
Mail.ReadWrite	メッセージの読み取り、検索、移動、フラグ設定、削除
Mail.Send	send_mail、返信、転送、mailto による配信停止
MailboxSettings.ReadWrite	受信トレイルール：list_rules、create_rule、delete_rule、block_sender
offline_access	更新トークン。サインインは一度だけで済みます

💡 0.1.0 からアップグレードする場合は、Azure でMailboxSettings.ReadWriteを追加し、force: trueを指定してloginを実行する（またはnpx -y @pepebits/outlook-mcp authを再実行する）必要があります。

💡 Azure ポータルの表示言語によってラベルが少し異なる場合があります（例：Administrar -> Autenticación -> Configuración、Permisos de OpenId）。

7. 概要ページでアプリケーション（クライアント）IDをコピーします。これがOUTLOOK_CLIENT_IDです。

🏢 職場または学校のアカウント： OUTLOOK_CLIENT_IDにアプリの ID を設定し、OUTLOOK_TENANT=organizations（またはテナントの GUID）を指定します。組織によっては、メールのアクセス許可に管理者の同意が必要な場合があります。

🧰 ツールリファレンス

ツール	変更	説明
login	いいえ	デバイスコードでのサインインを開始します。URL とコードを返します（再度サインインするには force を指定します）。
auth_status	いいえ	サインイン済み、サインイン保留中、またはサインアウト済みかを確認します。
logout	いいえ	サインアウトし、ローカルトークンキャッシュを削除します。
list_folders	いいえ	メールフォルダーまたは子フォルダーを一覧表示します（parentFolderId、includeHidden）。
list_messages	いいえ	新しいものから順にメッセージを一覧表示し、フィルター（unreadOnly、from、since、until、hasAttachments）と nextLink によるページ分けに対応します。
search_messages	いいえ	KQL の全文検索を行い、nextLink によるページ分けに対応します。
get_message	いいえ	宛先、フラグ、本文を含むメッセージ全体を取得します（format は text/html、maxChars）。
list_attachments	いいえ	メッセージの添付ファイルのメタデータを取得します。
download_attachment	いいえ	添付ファイルを OUTLOOK_DOWNLOAD_DIR に保存します（ローカルへの書き込みのみ。overwrite: true を指定しない限り上書きしません）。
send_mail	はい	メールを送信します。最大 150 MB のローカル添付ファイルを指定できます（3 MB 以上の場合はアップロードセッションを使用します。アップロードに失敗すると送信されません）。
create_draft	はい	送信せずに下書きを作成します。最大 150 MB の添付ファイルに対応します。アップロードの失敗は報告され、下書きは保持されます。
reply_message	はい	返信または全員に返信します（replyAll）。
forward_message	はい	新しい宛先に転送します。
move_message	はい	フォルダーに移動し、新しい ID を返します。id または ids（最大 50 件）を指定できます。
mark_read	はい	既読または未読にします。id または ids（最大 50 件）を指定できます。
flag_message	はい	flagged、complete、または notFlagged に設定します。id または ids（最大 50 件）を指定できます。
delete_message	はい	削除済みアイテムに移動します。または permanent: true を指定すると完全に削除します。id または ids（最大 50 件）を指定できます。
bulk_action	はい	query（KQL）またはフィルター（folderId、from、since、until、unreadOnly、hasAttachments）に一致するすべてのメッセージに、delete、move、archive、markRead、markUnread、flag、または unflag を適用します。デフォルトでは dryRun が有効です。max のデフォルトは 100（上限 500）です。
get_unsubscribe_info	いいえ	メッセージの送信元メーリングリストからの退会方法を表示します（List-Unsubscribe）。
unsubscribe	はい	メーリングリストから退会します。RFC 8058 のワンクリック方式、次に mailto リクエスト、いずれも使えない場合はリンクを返します。id または ids（最大 50 件）を指定できます。
find_newsletters	いいえ	フォルダーをスキャンし（folderId、最大 2000 件の maxMessages、excludeDomains、includeNoUnsubscribe）、送信者ごとにグループ化して、退会方法とともにメーリングリストを頻度の高い順に報告します。
mail_digest	いいえ	フォルダー内の未処理メールの概要を表示します（folderId、デフォルト 24 時間の since、デフォルト true の unreadOnly、最大 1000 件の maxMessages、groupBy は sender/none）。件数、重要度の高いメッセージとフラグ付きメッセージ、ニュースレターのヒントを添えた送信者別のグループを表示します。
list_rules	いいえ	受信トレイのルールを一覧表示します。
create_rule	はい	fromAddresses／senderContains／subjectContains と、move、delete、markRead、junk のいずれかのアクションを指定して、受信トレイのルールを作成します。
delete_rule	はい	ID を指定して受信トレイのルールを削除します。
block_sender	はい	addresses および／または domains をブロックするルールを作成し、該当する送信者から今後届くメールを削除済みアイテムに移動します。

一括操作：「id または ids を指定できます」と記載されたツールでは、どちらか一方のみを指定します。ids を指定すると、最大 50 件のメッセージを（一度に数件ずつ）処理します。最初のエラーで処理を中止することはなく、{ results: [{ id, ok, ... | error }], succeeded, failed } を返します。id を指定した場合、応答は変更されません。

フォルダー ID を指定する場所では、どこでも次の一般的なフォルダー名を使用できます：inbox、drafts、sentitems、deleteditems、junkemail、archive。

📬 毎日のダイジェスト

*「今日、受信トレイには何が届いていますか？」*と尋ねると、アシスタントはmail_digestを呼び出します。過去24時間の未読メールをスキャンし（since、unreadOnly、maxMessagesで調整できます）、件数（合計、未読、フラグ付き、重要度の高いもの、添付ファイル付き）と、重要度の高いメッセージおよびフラグ付きメッセージ、送信者ごとにまとめた最新の件名といくつかのメッセージIDを返します。上位20人の送信者についてはList-Unsubscribeヘッダーを確認するため、ニュースレターにはisNewsletterが付けられ、そのままunsubscribeに渡せます。

🧹 受信トレイを整理する

Claudeに、たとえば*「受信トレイを散らかしているニュースレターを見つけ、読まないものは購読を解除して、残りはブロックして」*と尋ねます。内部では、次の処理が行われます。

1. find_newslettersは受信トレイをスキャンし、List-Unsubscribeヘッダーがある送信者を頻度の高い順に一覧表示します。それぞれにsampleMessageIdとunsubscribe方法（one-click、mailto、link）が含まれます。
2. 選んだサンプルメッセージIDをidsに指定してunsubscribeを実行すると、該当リストの購読が解除されます。リンクのみを提供している送信者の場合は、ブラウザーで開くURLが返されます。
3. addressesまたはdomainsを指定してblock_senderを実行すると、今後届くメールを削除済みアイテムに送信する受信トレイのルールが作成されます。すでに受信トレイにあるメールを消去するには、idsを指定してdelete_messageを使います。ブロックを確認または取り消すには、list_rules／delete_ruleを使います。

受信トレイのルールにはMailboxSettings.ReadWrite権限が必要です（上記のAzureの手順を参照）。スパムやフィッシングの購読は解除しないでください。解除すると、アドレスが有効であることを相手に知らせてしまいます。代わりに送信者をブロックしてください。

🔎 検索による一括整理

*「2025年より前に受信した[email protected]からのメールをすべてアーカイブして」*と尋ねます。bulk_actionは常にドライランから始まり、何も変更せず、該当件数とメッセージのサンプル10件を返します。

{ "from": "[email protected]", "until": "2025-01-01", "action": "archive" }

アシスタントに件数を確認してから、dryRun: falseを指定してツールを再度呼び出し、操作を適用します。

{ "from": "[email protected]", "until": "2025-01-01", "action": "archive", "dryRun": false }

query（KQL。例：from:shop.com hasattachments:true）またはフィルターフィールドのどちらかを使い、両方は使わないでください。処理されるメッセージは最大max件です（デフォルトは100件、上限は500件）。結果がtruncatedかどうかは応答に示されます。残りのメッセージは再度実行して処理してください。deleteは削除済みアイテムに移動します（復元可能です）。archiveはアーカイブフォルダーに移動し、moveにはdestinationFolderIdが必要です。エラーが発生しても処理は停止せず、各IDの結果がokまたはerrorとして一覧表示されます。

👁️ 読み取り専用モード

OUTLOOK_READ_ONLY=trueを設定すると、変更を行わないツールのみが登録されます。変更を行うツールはクライアントに存在しないため、呼び出すことはできません。さらに防御を強化するには、User.Read Mail.Readだけを使って作成したトークンキャッシュと組み合わせます（OUTLOOK_SCOPESを適切に設定し、npx -y @pepebits/outlook-mcp authを再実行してください）。

🛡️ セキュリティ

• 🔑 トークンキャッシュは、利用可能な場合は OS のキーチェーン（macOS Keychain、Linux Secret Service。詳しくはトークンの保存を参照）に保存されます。それ以外の場合は、0700 ディレクトリ内のモード 0600 のローカルファイルにアトミックに書き込まれます。
• 🙅 クライアントシークレットはありません。デバイスコードフローを使用するパブリッククライアントです。
• 🤐 トークンとメッセージ本文がログに記録されることはありません。MSAL の PII ロギングは無効になっています。
• 📥 添付ファイルのダウンロード先は OUTLOOK_DOWNLOAD_DIR に限定されます。パストラバーサルは拒否されます。
• ⚠️ permanent: true を指定した delete_message は取り消しできません。また、send_mail、reply_message、forward_message はすぐに送信します。判断に迷う場合は、読み取り専用モードまたは create_draft を使用してください。
• 🧠 メールの内容は信頼できない入力です。悪意のあるメッセージによって、モデルに指示しようとする可能性があります（プロンプトインジェクション）。モデルがデータと指示を区別できるように、get_message、list_messages、search_messages、list_attachments、find_newsletters の結果では、送信者が制御できるテキスト（件名、送信者、プレビュー、添付ファイル名）を untrusted キーの下にまとめ、それを示す note を付与します。get_message の本文は <untrusted_email_content> マーカーで囲まれ、本文中にマーカーが含まれている場合は、囲みを早期に閉じられないよう無害化されます。
• 🤝 サーバーは MCP の instructions も送信し、メールの内容が信頼できないこと、また送信、削除、配信停止、ルールの変更にはユーザーの確認が必要であることをクライアントに伝えます。これらはリスクを軽減する手段であり、保証ではありません。これらの操作では人間が確認するようにするか、読み取り専用モードを使用してください。

🩺 トラブルシューティング

症状	対処方法
AADSTS7000218（クライアントアサーション／シークレットが必要）	Azure -> Manage -> Authentication -> Settings で Allow public client flows を有効にしてください。
AADSTS50020 またはテナントが正しくない	アカウントの種類が OUTLOOK_TENANT と一致していません。個人用には consumers、職場／学校用には organizations、両方には common を使用し、アプリ登録がそのアカウントの種類に対応していることを確認してください。
「Not signed in or session expired」	アシスタントに login の呼び出しを依頼するか、npx -y @pepebits/outlook-mcp auth を実行してください。
検索で「Invalid search query」が返される	search_messages は KQL を使用します。例：from:alice subject:"report" hasattachments:true。Graph が返す検索結果は最大約 250 件で、結果は並べ替えられません。
メッセージを移動した後に「Message not found」が表示される	メッセージを移動すると、メッセージ ID が変わります。move_message が返す newId を使うか、フォルダーを再度一覧表示してください。
「Access denied for inbox rules」	Azure -> API permissions で MailboxSettings.ReadWrite を追加し、OUTLOOK_SCOPES に含まれていることを確認してから、npx -y @pepebits/outlook-mcp auth を再度実行してください。
アクセス拒否／同意が必要	不足している委任されたアクセス許可を追加するか、管理者に同意を依頼してください。
クライアントでサーバーが起動しない	標準エラーのログを確認してください。独自のアプリを使用する場合、OUTLOOK_CLIENT_ID は .env またはクライアントの env ブロックで設定する必要があります。

🧑‍💻 開発

git clone https://github.com/Pepebits/outlook-mcp.git
cd outlook-mcp
npm install
cp .env.example .env        # optional
npm run build
npm test

MCP クライアントからソースコードを実行します：

claude mcp add outlook --scope user -- node /absolute/path/outlook-mcp/dist/index.js

npm run inspect を使って、MCP Inspector でツールを試してください。

🚢 リリース（メンテナー向け）

1. CHANGELOG.md の [Unreleased] の変更内容を新しいバージョンの下に移動し、package.json と server.json（トップレベルとパッケージ）のバージョンを更新してから、コミットしてプッシュします。
2. タグを付けます：git tag -a vX.Y.Z -m "Short summary" && git push origin vX.Y.Z。Release ワークフローがテストを実行し、npm にバージョンをステージングし（Trusted Publishing、プロビナンス付き）、GitHub リリースを作成します。
3. npmjs.com でステージングされたバージョンを承認します（または npm stage approve <stage-id> を実行します）。承認には 2FA が必要です。
4. ワークフローは承認を待ち、MCP Registry にバージョンを登録して、Telegram でリリースを告知します。承認が約 6 時間以上遅れると待機がタイムアウトします。その場合は、タグを指定して Release ワークフローを手動で実行し（Actions → Release → Run workflow）、告知してください。

🗺️ ロードマップ

このサーバーはメール専用です。カレンダーやその他の Microsoft 365 データは対象外です。

現在、予定しているものはありません。アイデアをお待ちしています：issue を作成してください。

🤝 貢献

issue やプルリクエストを歓迎します。

npm install
npm run typecheck
npm test
npm run build

コード、コメント、ドキュメントは英語で記述し、新しい動作にはテストを追加してください。また、シークレットやメッセージの内容をログに記録しないでください。

📄 ライセンス

MIT