office-outlook-mcp

office-outlook-mcp

Outlook / Microsoft 365 用の MCP サーバーです。メール、フォルダー、カレンダー、連絡先、タスクに対応し、送信には確認が必要です。

このプロジェクトは AI（Claude Code）によって開発・保守されています。ご自身の判断でご利用ください。

認証の仕組み

Outlook Web はアクセス トークンをメモリ内に保持し、Authorization: Bearer … として送信します。このサーバーは、サインイン済みのブラウザータブから fetchproxy ブリッジ経由でそのヘッダーを取得し、通常のサーバー側リクエストで https://outlook.office.com/api/v2.0 と通信します。

ブラウザーが必要なのはトークンの取得時（約25時間ごと）だけで、API 呼び出しには必要ありません。 これが設計のすべてです。Azure アプリの登録も、管理者の同意も、リクエスト経路上のブラウザーも不要です。

トークンは ~/.office-outlook-mcp/token.json（0600）にキャッシュされるため、再起動後に再取得する必要はありません。

インストール

npm i -g @chrischall/office-outlook-mcp

リリースからインストールできる ContextMint Bridge ブラウザー拡張機能が必要です。Chrome では、Chrome ビルドを解凍し、展開して読み込んでください（chrome://extensions → デベロッパー モード → 展開して読み込む）。Safari 版はまだ利用できません。一般公開されていない ContextMint アプリに組み込まれて提供される予定なので、今のところは Chrome を使用してください。

ContextMint Bridge は、同じメンテナーによる fetchproxy ブラウザー拡張機能の新しい名称です。fetchproxy 自体の README（#extension）からも案内されています。ソースは公開されています。ご自身でビルドするか、リリース ZIP を同梱の .sha256 ファイルと照合してください（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

拡張機能、fpx、このサーバーは、パッケージのバージョンではなくfetchproxy プロトコル番号（現在はプロトコル 4）によって互換性が決まります。Bridge と fpx を最新の状態に保ってください。不一致があると、両方のプロトコル番号を示すエラーが発生します。また、@fetchproxy/cli もインストールしてください。

npm i -g @fetchproxy/cli

初回のトークン取得時に6桁のペアコードが表示されるので、ContextMint Bridge のポップアップで承認してください。許可はその後も保持されます。

opencode へのインストール

opencode は MCP サーバーの設定を opencode.json（プロジェクト用）または ~/.config/opencode/opencode.json（グローバル用）から読み込みます。

{
  "mcp": {
    "servers": {
      "outlook": {
        "type": "local",
        "command": ["npx", "-y", "@chrischall/office-outlook-mcp"]
      }
    }
  }
}

この1つのファイルは opencode 2 と現行の opencode 1 の両方で使えます。2.0.11、1.18.31、1.18.28 で実際に検証済みで、いずれもこのファイルから接続できます。

実測に基づく注意点が2つあります。

• 1つのファイルに両方の設定形式を含めないでください。 古い opencode 1 では、サーバーを mcp の直下に記述する必要があります（"mcp": { "outlook": { … } }）。どちらのバージョンでも使えるように両方を記述したくなりますが、そうしてはいけません。servers と同階層に別のキーがあると、opencode 2 はファイルを解析します（opencode debug config にも表示されます）が、その後 "No MCP servers configured" と報告します。エラーも警告もなく、すべてのサーバーがひそかに無効になります。
• 古い opencode 1 が servers を受け付けない場合は、その旨が明確に表示されます（Configuration is invalid at …）。その場合は、両方の形式を組み合わせるのではなく、そのマシンの設定をフラット形式に切り替えてください。

opencode 2 はバックグラウンド サービスと通信するため、設定を編集した後、opencode mcp list の前に opencode reload を実行してください。

設定

すべて省略可能です。何も設定しない場合、サーバーはブラウザーから取得します。

variable	purpose
OUTLOOK_ACCESS_TOKEN	事前に取得したベアラートークンです。ブリッジより優先されます。上級ユーザーまたは CI 専用です。有効期限は約 25 時間で、自動更新できません。
OUTLOOK_DISABLE_FETCHPROXY	1 にするとブラウザーからの取得を無効にし、OUTLOOK_ACCESS_TOKEN が必須になります。
OUTLOOK_API_BASE	REST ベース URL を上書きします。既定値は https://outlook.office.com/api/v2.0 です。
OUTLOOK_WS_PORT	fetchproxy の集約ポートです。既定値は 37149 で、全環境で共有されるポートです。
OUTLOOK_CAPTURE_TIMEOUT	タブが読み取り可能なリクエストを行うまで待機する秒数です。宣言された 2 つのホストを含む、取得処理全体のタイムアウトを設定します。既定値は 30 です。
OUTLOOK_TOKEN_CACHE	false にすると、実行間でトークンをキャッシュしません。
OUTLOOK_TOKEN_FILE	キャッシュされたトークンのパスです。既定値は ~/.office-outlook-mcp/token.json です。
OUTLOOK_OUTPUT_DIR	outlook_export_messages と outlook_export_events の出力先となる絶対パスのディレクトリです。既定値は ~/Downloads/office-outlook-mcp です。設定した場合、呼び出しごとの dest はそのディレクトリ内に指定する必要があります。一括エクスポートを参照してください。

ツール

読み取り — outlook_list_folders、outlook_list_messages、 outlook_get_message、outlook_list_unread_messages、outlook_list_attachments、 outlook_get_attachment、outlook_list_events、outlook_get_event、 outlook_list_calendars、outlook_find_meeting_times、 outlook_get_schedule、outlook_get_profile、 outlook_get_mailbox_settings、outlook_list_contacts、outlook_list_people、 outlook_list_categories、outlook_list_tasks

書き込み（先に確認を求めます。確認を参照） — outlook_send_message、outlook_create_draft、outlook_mark_read、 outlook_update_message、outlook_move_message、outlook_create_event、 outlook_update_event、outlook_respond_to_invite、outlook_delete_event、 outlook_reply。 ほかの人には何も届かないため、確認を省略するものもあります。 outlook_create_draft（Outlook から送信するまで、下書きは「下書き」に残ります）、draftOnly: true を指定した outlook_reply（返信は「下書き」に残ります）、sendResponse: false を指定した outlook_respond_to_invite、および参加者のいない自分の予定、または開催者がすでにキャンセルした会議に対する outlook_delete_event（いずれの場合も、自分のカレンダーだけが変更されます）。

会議 — outlook_find_meeting_times は Outlook のスケジュールアシスタントに、全員の空き時間帯を問い合わせます。outlook_get_schedule は各人の予定ありの時間帯を表示します。提案された各時間帯には createEventArgs が含まれ、これは outlook_create_event にそのまま渡せます。outlook_create_event は既定で Microsoft Teams の会議を追加し、参加リンクを返します。teamsMeeting: false を渡すと追加されません。outlook_update_event は、明示的に求められない限り、会議への参加方法を変更しません。Teams 会議が設定されていないイベントに追加するには teamsMeeting: true を渡します。その場合、確認メッセージにはその旨がわかりやすく表示されます。会議を更新できるのは開催者だけです。outlook_respond_to_invite は、メッセージ ID またはイベント ID を指定して、招待を承諾、仮承諾、または辞退します。 outlook_delete_event は、自分が開催するイベントを削除します。1 件の開催分はその開催分の ID で、シリーズ全体はシリーズマスターの ID で削除し、参加者にはキャンセル通知を送信します。受信した招待については削除を拒否し、代わりに辞退するよう案内します。outlook_list_events と outlook_get_event は、どの表示形式でも判断に必要な情報を表示します。具体的には、MyResponse、ResponseRequested、IsOrganizer、IsCancelled、Type（SingleInstance、Occurrence、Exception または SeriesMaster）、ShowAs、IsAllDay で、全項目を含む表示では SeriesMasterId も表示します。

エクスポート — outlook_export_messages（メール）と outlook_export_events （カレンダー）は、添付ファイルを含めることもできる JSONL ファイルまたは Markdown ファイルを書き出し、保存先のみを返します。一括エクスポートを参照してください。

診断 — outlook_healthcheck すべての読み取りツールでは、view: compact | full | raw を指定でき、デフォルトは compact です。 変更を行うツールは、確認するまで何も書き込みません（上記のケースを除きます） — 確認を参照してください。プレビューには、送信される内容（アクション、メソッド、パス、本文）が正確に表示されます。（outlook_create_event は最初にメールボックスのタイムゾーンを読み取るため、プレビューには予定を登録するタイムゾーンを表示できます。プレビューで行われる読み取りはこれだけです。）

メールや予定の本文はほかの人が書いたものなので、outlook_list_messages、outlook_get_message、outlook_list_unread_messages、outlook_get_attachment、outlook_list_events、outlook_get_event、outlook_find_meeting_times、outlook_get_schedule、outlook_export_messages、outlook_export_events は、すべての結果（すべてのビュー）を信頼できないコンテンツのエンベロープで囲みます。エンベロープには untrusted_content: true と、テキストを指示ではなくデータとして扱うようモデルに伝える note が含まれます（独自の untrusted_content／note キーを持つ view: raw のレコードは data の下にネストされるため、エンベロープを上書きできません）。outlook_reply は、送信した返信の件名（元の送信者のテキスト）を同じエンベロープ内で返します。 確認プロンプトを表示できないクライアントでは、confirmToken は引き続きモデル自身が返すものです。そのため、MCP_CONFIRM_MODE=ask-user（デフォルト）を維持して、チャットで各プレビューを承認するか、読み取り専用ではないツールの実行前に確認を求めるクライアントを使用してください。これが送信を防ぐ実際のガードになります。

トリアージの流れ

エージェントは Outlook を開かずに、新着メールへの対応を最初から最後まで行えます。

1. メールをまとめて読む — outlook_list_unread_messages は、フォルダー（デフォルトは受信トレイ）内の未読メッセージを新しい順に、プレーンテキスト本文付きで一度の呼び出しで返します。既読にはしません。各項目には kind があり、値は mail、meetingRequest、meetingCancelled、meetingResponse のいずれかです。会議出席依頼とキャンセルには、関連付けられた event（日時、開催者、現在の応答状況）も含まれます。会議がすでにカレンダーにない場合（すでに辞退、キャンセル、削除されている場合）は、応答するものがないことを示す hint が含まれます。to と cc に表示されるアドレスはそれぞれ最大20件で、それ以上ある場合は toCount／ccCount で件数が示されます。
2. 各項目に対応する —
   • 招待：メッセージ ID と accept、tentative、decline のいずれか（および任意のコメント）を指定して outlook_respond_to_invite を使用します。応答すると、Outlook は招待メッセージを新しい ID で「削除済みアイテム」に移動するため、回答済みの招待はすでに整理されています。その招待については手順3と4を省略してください（古い ID は404になります）。
   • 返信が必要なメッセージ：outlook_reply（reply、replyAll、forward）を使用するか、draftOnly: true を指定して、確認できるよう「下書き」に残します。
   • 会議の依頼：出席者を指定して outlook_find_meeting_times を実行し、選んだ時間枠の createEventArgs を outlook_create_event に渡します。
   • 添付ファイルの閲覧：outlook_get_attachment を使用します。
3. 整理する — outlook_update_message を使うと、1回の呼び出しで最大50件のメッセージにフラグを付け、カテゴリを設定し（カテゴリ名は outlook_list_categories で確認）、既読にできます。outlook_move_message は1件のメッセージを別のフォルダーに移動します。
4. 対応済みにする — 対応した通常のメールには outlook_mark_read（または outlook_update_message の isRead: true）を使用します。これにより、次回の outlook_list_unread_messages では未対応の新着メールだけが返されます。回答済みの招待はすでに受信トレイから移動されています（手順2を参照）。

返信、転送、招待への応答、新しい会議はほかの人に届くため、いずれも事前の確認が必要です。ただし、draftOnly: true を指定して保存した返信（送信するまで「下書き」に残ります）と、sendResponse: false を指定した招待への応答（自分のカレンダーだけが変更され、開催者には通知されません）は除きます。

時刻からのページング

outlook_list_unread_messages と outlook_list_messages は、指定した時刻から古い順にページングすることもできます。from に ISO 8601 UTC 時刻（2026-10-01T00:00:00Z）を渡します。結果には next_from と has_more が含まれます。次のページでは、next_from を変更せずに from として渡してください。過去のメールを取り込むには、古い時刻から開始し、has_more が false になるまで next_from を渡し続けます。その後は最後の next_from を使ってポーリングを続け、新着メールを取得します（空のページでは同じ位置が返されます）。タイムスタンプが同じメッセージがページをまたいで欠落したり重複したりすることはなく、ページ間にメールを既読にしても取りこぼしはありません。from は nextLink、sinceHours、search、または skip と組み合わせられません。

一括エクスポート

outlook_export_messages はメールを、outlook_export_events はカレンダーを、それぞれ一度に数千件ずつ一括エクスポートします。これらの本文が会話に含まれることはありません。サーバーはメールボックス（またはカレンダー）をページングし、レコードをファイルに書き込みます。ツールが返すのは小さなマニフェストのみです。ファイルの場所、サイズ、レコード数と添付ファイル数、対象期間、および has_more と cursor が含まれます。ファイル全体を開くのではなく、シェルツール（jq、grep、rg、head）でファイルを読み取るようエージェントに指示してください。

• メールの引数： folder（inbox や sentitems などの既知の名前、またはフォルダー ID。all はメールボックス全体をエクスポートします。デフォルトは inbox）、since と until（ISO 8601）、search（メールボックス全体を対象とする全文検索）。メールは古い順にエクスポートされます。
• イベントの引数： since と until（ISO 8601、両方必須、期間は最大 2 年）と calendar（カレンダー ID。デフォルトは既定のカレンダー）。イベントはカレンダービューから取得されるため、定期的な予定は個別の予定に展開されます。時刻はメールボックスのタイムゾーンにおける壁時計時刻で、各レコードの time_zone にタイムゾーン名が記載されます。
• 両方に共通： format（デフォルトの jsonl、または markdown）、attachments（デフォルトは false）、dest、cursor、max_items（デフォルトは 5000、最大 50000）、budget_seconds（デフォルトは 90、最大 600）。
• ファイル： part-0001.jsonl には、メッセージごとに 1 つの JSON レコードが格納されます（id、conversation id、件名、差出人、宛先/cc/bcc、日付、フラグ、カテゴリ、Web リンク、プレーンテキストの本文全文）。最初の行は _export ヘッダーで、ソース、アカウント、引数、および信頼できないコンテンツに関する注記が記載されます。イベントレコードには、id、iCal UID、種類とシリーズ ID、件名、開始、終了、タイムゾーン、場所、開催者、各自の応答を含む出席者、あなたの応答、表示方法、カテゴリ、参加リンク、プレーンテキストの本文全文が含まれます。 format: "markdown" を指定すると、代わりに読みやすい記録（メッセージまたはイベントごとに 1 セクション）を part-0001.md に書き込みます。 manifest.json には件数、エラー（発生した場合）、ファイルが記載されます。ディスク上では各パートのファイル（各パートの完了時に書き換えられます）、blob zip 内ではその zip 内のファイルが記載されます。
• 添付ファイル： attachments: true の場合、最大 50 MB の各ファイル添付が attachments/<short id>/<name> に保存されます（名前はサニタイズされます）。レコードには各添付ファイルの相対 path、または skipped とその理由が記載されます。添付された Outlook アイテム（転送メールまたはイベント）、クラウドファイルへのリンク（OneDrive/SharePoint）、サイズの大きなファイル、ダウンロードに失敗したファイルはスキップされます。添付ファイルが 1 つ取得できなくてもエクスポート全体が失敗することはありません。
• 再開： 各呼び出しは max_items または budget_seconds のいずれかに達した時点で停止します。has_more が true の間は、cursor を変更せずに渡してください。次の呼び出しでは、同じエクスポートの続きを part-0002、part-0003 のように作成します。添付ファイルの取得を有効にしている場合、予算はレコードの小さなグループごとに確認されるため、ページの途中で停止することがあります。カーソルを使うと次のレコードから再開します。添付ファイルのダウンロード中を含め Outlook が認証情報を拒否した場合、または Retry-After の待機を 3 回行った後も 429 を返し続ける場合、呼び出しはすでに書き込まれたデータを保持してカーソルを返します。再認証してから再開してください。

ファイルの保存先は、サーバーの実行方法によって異なります。

モード	条件	結果内のlocation
disk	ローカル（stdio）でのすべてのインストール。デフォルトです	絶対パスのローカルディレクトリ、<dir>/outlook-mail-<YYYYMMDD-HHmmss>/（またはoutlook-events-…）。各ファイルの項目には絶対パスのpathが含まれます
blob	MCP_BLOB_BASE_URLとMCP_BLOB_SIGNING_KEYの両方を設定したmcp-host上でのホスティング	呼び出しごとに1つのzip（manifest.jsonを含むpart-NNNN.zip）をダウンロードするための署名付きリンク。有効期間は1時間です（url_expires_at）

ディスク上では、<dir>は呼び出しごとのdest、それがなければOUTLOOK_OUTPUT_DIR、それもなければ ~/Downloads/office-outlook-mcpです。OUTLOOK_OUTPUT_DIRが設定されている場合、destはその配下でなければなりません。 そうでない場合は、~/Downloads、~/Documents、~/Desktopのいずれかの配下でなければなりません。再開時のカーソルのディレクトリも、同じルートに対して再度チェックされます。

確認

新しい下書き、下書きのみの返信、通知なしの招待への応答を除き、書き込みの前には必ず確認を求めます（詳しくは ツールを参照してください）。確認プロンプトを表示できるクライアント（Claude Code）では、プロンプトが表示されます。表示できないクライアントでは、最初の呼び出しは何もせず、confirmation-requiredのプレビューとconfirmTokenを返します。そのトークンを使って再度呼び出すと、書き込みが実行されます。トークンは1回のみ使用でき、有効期限があり、引数の完全一致が必要です。2回の呼び出しの間に何かを変更すると、書き込みは拒否され（DRAFT_CHANGED）、新しいプレビューが返されます。

変数	デフォルト値
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込みを行う場合の動作です。ask-user：2段階で実行します。最初の呼び出しは何もせず、プレビューとトークンを返します。モデルはチャットでユーザーの承認を得てから、トークンを使って再度呼び出す必要があります。auto：同じく2段階で実行しますが、モデルはプレビューを自ら確認した後、トークンを使用できます。refuse：そのようなクライアントでは書き込みを拒否します。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=offの場合を除き、常に実際のプロンプトが表示されます。認識されない値はrefuseとして扱われます。
MCP_CONFIRM_ELICITATION	on	offにすると確認プロンプトは表示されず、すべてのクライアントにMCP_CONFIRM_MODEの動作が適用されます。プロンプトを表示できると伝えているのに実際には表示しないクライアント（書き込みがハングするopencode 2.0.x）に設定してください。それ以外の値はonとして扱われ、stderrに警告が表示されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。サーバーの再起動後もトークンを有効にする必要がある場合にのみ設定してください。mcp-hostでは、ホストが子プロセスごとに安定したキー（MCP_HOST_CONFIRM_SECRET）を指定し、使用済みトークンをMCP_DATA_DIRに記録するため、アイドル状態からの再起動後も承認が保持されます。

知っておくと便利なこと

• フィールド名はPascalCase（ReceivedDateTime、IsRead）です。これはOutlook REST APIであり、Graphではありません。Graphのスニペットは何も返さず、気づきにくいので注意してください。
• outlook_get_messageはデフォルトでプレーンテキストの本文を返します。HTMLと比べてサイズは9.4分の1です。元の形式を取得するにはhtml: trueを渡してください。
• outlook_list_eventsはカレンダーのビューを使うため、定期的な予定シリーズが展開されます。/me/eventsでは展開されないため、そのままの形では公開していません。
• タイムゾーンにはIANA名ではなく、Windows名（Eastern Standard Time）を使います。
• searchとunreadOnlyは併用できません。APIは$searchと$filterの併用を拒否するため、このツールは失敗するリクエストを送信する前に拒否します。
• メッセージを移動すると、新しいIDが割り当てられます。
• timeZoneで上書きしない限り、outlook_list_eventsはメールボックス固有のタイムゾーンで時刻を返します。API自体のデフォルトはUTCであり、東部時間のメールボックスでは、気づかないまま4時間の誤差として読み取られます。
• 連絡先の電話番号フィールドはMobilePhone1であり、GraphのMobilePhoneではありません。v2.0のContact型にGraphの名前を指定すると、400エラーになります。

軽量な代替手段

このマシン上の Claude Code から Outlook にアクセスするだけであれば、このリポジトリの skills/outlook-fpx アクセススキルで、fpx と curl を使って同じ読み取りを実行できます。サーバーは一切不要です。型付きツール、 確認を経て実行される書き込み、または claude.ai からのアクセスが必要な場合に、MCP が役立ちます。

開発

npm install
npm run build
npm test              # typecheck + suite
npm run test:coverage # CI's gate

リクエストの形式は、実際のメールボックスで検証済みの docs/OUTLOOK-API.md に記載されています。

ライセンス

MIT