MSGraph MCP

MSGraph MCP

Microsoft Graph 用の Model Context Protocol（MCP）サーバーです。Microsoft Graph SDK を介して、Microsoft Outlook のメールとカレンダーに加え、Microsoft Teams のメッセージ履歴（読み取り専用）を AI エージェントに公開します。委任されたアクセス許可と MSAL デバイスコードフローを使用し、サインインしたユーザーとして動作するため、そのユーザーがアクセスできる範囲に限りアクセスできます。

インストール

Python ≥ 3.11 と Entra（Azure AD）のアプリ登録が必要です。アプリ登録には約 10 分かかり、管理者が必要な場合もあるため、先に済ませてください。以下の Entra のセットアップのセクションを参照してください。

uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server

パッケージ名は msgraph-mcp-server です。3 つのコマンドがインストールされます。msgraph-mcp とそのエイリアス msgraph-mcp-server はどちらも stdio サーバーを起動し、msgraph-mcp-login は初回サインインに使用します。

セットアップ

1. Entra アプリの認証情報を設定します。

export MSGRAPH_MCP_CLIENT_ID=<your app's client ID>
export MSGRAPH_MCP_TENANT_ID=<your tenant ID>   # or: common / organizations / consumers

2. 一度サインインします。 URL とコードが表示されます。URL にアクセスしてコードを入力してください。クライアントシークレットは使用も保存もされません。

msgraph-mcp-login
# running via uvx instead of installing: uvx --from msgraph-mcp-server msgraph-mcp-login

トークンキャッシュは ~/.msgraph-mcp/token_cache.bin に書き込まれます。

3. サーバーを MCP ホストに接続します。

Claude Code：

claude mcp add msgraph \
  --env MSGRAPH_MCP_CLIENT_ID=$MSGRAPH_MCP_CLIENT_ID \
  --env MSGRAPH_MCP_TENANT_ID=$MSGRAPH_MCP_TENANT_ID \
  -- msgraph-mcp

その他のホストの場合は、stdio を使用します。

{
  "mcpServers": {
    "msgraph": {
      "command": "msgraph-mcp",
      "args": [],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<your app's client ID>",
        "MSGRAPH_MCP_TENANT_ID": "<your tenant ID>"
      }
    }
  }
}

インストールせずに実行するには、"command": "uvx" と "args": ["msgraph-mcp-server"] を使用します。uvx は msgraph-mcp-login を PATH に追加しないため、サインインには手順 2 に示した uvx --from 形式を使用してください。

MSGRAPH_MCP_TOKEN_CACHE_PATH を指定すると、キャッシュの場所を任意で上書きできます。3 つの変数すべてを作業ディレクトリ内の .env ファイルから読み込むこともできます。プロセス環境変数が .env ファイルより優先されます。

Entra のセットアップ

アプリ登録には以下が必要です。

• アカウントの種類： シングルテナント（マルチテナントも使用できます。その場合は MSGRAPH_MCP_TENANT_ID を common、organizations、または consumers に設定してください）
• リダイレクト URI（パブリッククライアント）： https://login.microsoftonline.com/common/oauth2/nativeclient
• パブリッククライアントフローを許可： 「認証」→「詳細設定」で「はい」に設定します。これを設定しないと、デバイスコードフローは失敗します。
• 委任されたアクセス許可（Microsoft Graph）：
  • メール：Mail.ReadWrite、Mail.ReadWrite.Shared、Mail.Send
  • ルール：MailboxSettings.ReadWrite（Graph の messageRules エンドポイントに必要です）
  • カレンダー：Calendars.ReadWrite、Calendars.ReadWrite.Shared
  • ID：User.Read
  • Teams：Chat.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Read.All

ChannelMessage.Read.All には常にテナント管理者の同意が必要です。また、*.Shared のアクセス許可にも、テナントによっては管理者の同意が必要です。

スコープの一覧はすべて一括で適用されます。 サインイン時にすべてのスコープが一度に要求されるため、ChannelMessage.Read.All に対する管理者の同意がないと、サインイン自体が失敗し、メールとカレンダーも利用できません。同じ理由から、後でスコープを追加した場合は msgraph-mcp-login を再実行する必要があります。再実行するまでは、新しいスコープを必要とするツールだけでなく、すべてのツールが NotAuthenticatedError で失敗します。

ツール

グループ	ツール
ユーティリティ	whoami
メール — 読み取り	list_messages, search_messages, get_message, list_attachments, download_attachment
メール — 書き込み	send_message, create_draft, reply_message, reply_all_message, forward_message, update_message, delete_message
メール — フォルダー	list_folders, create_folder, update_folder, delete_folder, move_message
メール — アクション	archive_message, mark_read, mark_unread, flag_message, unflag_message
メール — 一括	batch_archive_messages, batch_move_messages, batch_mark_read, batch_mark_unread, batch_flag_messages, batch_unflag_messages
メール — ルール	list_rules, get_rule, create_rule, update_rule, delete_rule
カレンダー	list_calendars, list_events, get_event, create_event, update_event, delete_event, cancel_event, respond_to_event, find_meeting_times
Teams（読み取り）	list_chats, list_chat_messages, list_joined_teams, list_channels, list_channel_messages, list_message_replies, download_hosted_content

ツールに共通する動作：

• 応答の簡略化。 結果はエージェント向けに整形され、メッセージとイベントの本文は短い snippet に置き換えられます。get_message、list_chat_messages、list_channel_messages、または list_message_replies に include_body=true を渡すと、本文全体を取得できます。Teams の場合、Adaptive Card のコンテンツも表示されます。Graph オブジェクトを返す任意のツールに include_raw=true を渡すと、簡略化された結果とともにペイロード全体を取得できます。ただし、batch_* ツールはメッセージごとのステータスのみを返し、このオプションは受け付けません。
• 他のメールボックス。 すべてのメールおよびカレンダーのツールでは、共有または委任されたメールボックスを対象にするため、オプションの mailbox（メールアドレスまたはユーザー ID）を指定できます。自分のメールボックスを対象にする場合は省略してください。Teams ツールは読み取り専用で、自分のチャットのみを対象とし、mailbox は指定できません。
• ページネーション。 一覧表示および検索のツールでは、Graph により上限が 50 に設定されている list_channel_messages と list_message_replies を除き、limit（1～100、デフォルトは 25）と page_token を指定できます。list_folders、list_rules、list_attachments、list_calendars はコレクション全体を返し、どちらも受け付けません。list_joined_teams と list_channels では、Graph が $top を拒否するため、取得後に limit が適用されます。そのため、往復回数ではなくトークン数を節約できます。
• 一括操作。 batch_* ツールは、Graph の $batch エンドポイントを使って最大 1000 件のメッセージに一つのアクションを適用し、メッセージごとの結果と {total, succeeded, failed} の概要を返します。
• ダウンロード。 download_attachment と download_hosted_content は、エージェントが表示できるネイティブ MCP 画像ブロックとして画像を返します。代わりに save_path（ファイルまたは既存のディレクトリ）を渡すと、バイトデータをディスクに書き込み、パスを返します。
• メールの検索。 list_messages は既定で受信トレイを対象とします。別のフォルダーを対象にするには folder_id、未読のみに絞り込むには unread_only=true、KQL では表現できない条件を指定するには生の OData filter を渡してください。search_messages はクエリを KQL として Graph の $search に渡します。

送信する添付ファイルは、メッセージごとに合計 3 MB までです。チャンク分割アップロードはサポートされていません。SharePoint を利用する Teams のファイル添付はダウンロードできず、インラインのホストされたコンテンツのみダウンロードできます。

セキュリティ

トークンキャッシュには、メール、カレンダー、Teams のデータにアクセスするトークンを発行できるリフレッシュトークンが保存されます。このファイルは認証情報として扱ってください。保存場所は ~/.msgraph-mcp/token_cache.bin で、0700 ディレクトリ内にモード 0600 で保存されます。

アクセスを取り消す場合や、アカウントを切り替える場合は、キャッシュを削除して再度サインインしてください。

rm -f ~/.msgraph-mcp/token_cache.bin ~/.outlook-mcp/token_cache.bin

2 つ目のパスが重要なのは、このサーバーを以前の名前 outlook-mcp で実行したことがある場合です。現在のキャッシュが存在しないときは、そのキャッシュが引き続きフォールバックとして使われるため、最初のファイルだけを削除しても、ディスク上には有効なリフレッシュトークンが残ります。アクセスを完全に取り消すには、https://account.microsoft.com または組織の ID ポータルでアプリも削除してください。

トラブルシューティング

• NotAuthenticatedError: Not authenticated — msgraph-mcp-login を実行してください。すぐに再発する場合は、要求されたスコープにまだ同意していません。Entra の設定に関する注記を参照してください。
• ConfigError: Missing required env var — シェル、作業ディレクトリ内の .env、または MCP ホストの環境変数設定で値を設定してください。
• Graph API 403: ErrorAccessDenied — Entra アプリに委任されたアクセス許可がないか、管理者の同意が必要です。上記の一覧を確認し、再度同意してサインインしてください。
• search_messages で発生する Graph API 400: BadRequest — Syntax error — クエリは KQL として Graph の $search に送られます。リテラルのフレーズ（"weekly report"）を引用符で囲むか、フィールド指定形式（from:alice）を使用してください。KQL で表現できない条件には、filter= を指定して list_messages を使用してください。
• ホストはサーバーを起動するものの、ツールが表示されない — stdio 経由で msgraph-mcp（または uvx）を起動していること、およびそのバイナリを PATH から見つけられることを確認してください。

開発

CONTRIBUTING.md を参照してください。