ms-graph-mcp

ms-graph-mcp

リリース · 変更履歴

Microsoft Graph 用の Model Context Protocol サーバーです。メール、カレンダー、会議（文字起こしを含む）、Teams チャット、ファイル、SharePoint、検索、ユーザー、連絡先、ディレクトリ、タスク、OneNote にわたる 85 個のツールを、stdio または Streamable HTTP 経由で提供します。

ご自身の Microsoft アカウントでサインインします — ブラウザー SSO を使うため、トークンの貼り付けもクライアントシークレットも不要です。

• msgraph-sdk も azure-identity も不要 — Graph クライアントは httpx2 を直接使用するため、依存関係ツリーが小さく、通信の動作も確認できます。
• 読み取りと書き込みの分離は推奨ではなく強制されます — 呼び出し元が明示的に許可しない限り、書き込みツールは非表示になり、実行も拒否されます。
• デフォルトでは認証方式に依存しません — ツールは、リクエストコンテキストを通じて取得済みの Graph トークンを受け取ります。サーバー自身にオンビハーフオブ交換を実行させ、適切な OAuth リソースサーバーとして動作させることもできます。

ステータス：初期段階です。 実際のテナントに対して稼働している、本番環境のエージェントプラットフォームから切り出されました。コードは実運用で十分に検証されていますが、パッケージ化と公開 API は新しいものです。1.0 より前に設定項目が変更される可能性があります。

インストール

Python 3.12 以降が必要です。方法は 2 つあります。目的に合った方を選んでください。

A. パッケージを使用する

クローンは不要です。uv を使えば、PyPI からそのまま実行できます。

uvx --from ms-graph-mcp ms-graph-mcp          # stdio, for an MCP client
uvx --from ms-graph-mcp ms-graph-mcp-http     # Streamable HTTP

または、環境にインストールします。

pip install ms-graph-mcp

リリース候補も公開されています。pip は、指定しない限りこれらをスキップします。

pip install --pre ms-graph-mcp          # newest, including candidates
pip install ms-graph-mcp==0.3.0rc1      # a specific one; no --pre needed for an exact pin

HTTP トランスポート用のコンテナーイメージは GHCR で公開されています。docs/hosting.md を参照してください。

公式 MCP レジストリにも io.github.nitin27may/ms-graph-mcp として登録されています。

TestPyPI は配布先ではありません。 各リリースはまずそこに公開されますが、これは公開プロセスのリハーサルです。予告なく削除される可能性があり、PyPI のミラーでもないため、通常の依存関係を解決するだけでも --extra-index-url https://pypi.org/simple/ が必要です。PyPI または --pre を使用してください。

B. ソースから実行する

開発、フォーク、または未リリースの変更を実行する場合：

git clone https://github.com/nitin27may/ms-graph-mcp
cd ms-graph-mcp
uv sync                       # creates .venv and installs everything
uv run ms-graph-mcp           # check it starts

セットアップに必要なのは uv sync だけです。プルリクエストを作成する前に CONTRIBUTING.md を確認してください。ツールの許可リストと階層の分離には、不変条件があり、推奨ではなく強制されています。

MCP クライアントからクローンを指定するには、絶対パスが必要です。クライアントは作業ディレクトリを引き継がず、ほとんどの場合 ~ も展開しません。

cd ms-graph-mcp && pwd
# /Users/you/workspace/ms-graph-mcp

次に、以下のソースから実行する場合の設定を使用してください。

Entra アプリを設定する

Entra ID アプリの登録が必要です。所要時間は約2分です。クライアントシークレットは作成しないでください。 このアプリはパブリッククライアントとして登録され、PKCE を使用してブラウザー経由でサインインします。ご自身のマシンで実行するプログラムのシークレットは、設定ファイルを持つ人なら誰でも読み取れるため、このフローではシークレットを必要としない設計になっています。設定ファイルに記載するのは2つの ID だけで、どちらも機密情報ではありません。

Entra ポータル → アプリの登録 → 新規登録で設定します。

• 名前： 任意の名前（例：ms-graph-mcp）
• サポートされているアカウントの種類： この組織のディレクトリ内のアカウントのみ
• リダイレクト URI： パブリック クライアント/ネイティブを選択し、値にhttp://localhostを指定

証明書とシークレットはそのままにしてください。ここから必要なものはありません。

次に、新しいアプリで以下を設定します。

• 認証 → パブリック クライアント フローを許可するを有効にする

• API のアクセス許可 → アクセス許可の追加 → Microsoft Graph → 委任されたアクセス許可を選択し、エージェントにアクセスさせたいものを追加します。読み取り専用で始める場合は、以下のセットが適しています。

  User.Read  Mail.Read  Calendars.Read  Files.Read.All
  People.Read  Chat.Read  Tasks.Read  Notes.Read  Contacts.Read
  

  コピーして同意できるアクセス許可セットの全一覧と、各ツールに必要なアクセス許可については、docs/permissions.mdをご覧ください。

概要ページからアプリケーション（クライアント）IDとディレクトリ（テナント）IDをコピーします。必要なものはこれですべてです。

MCP クライアントを設定する

stdio に対応するすべての MCP クライアントで必要なのは、コマンド、その引数、環境変数ブロックの3つです。

{
  "command": "uvx",
  "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
  "env": {
    "GRAPH_MCP_CLIENT_ID": "<application-client-id>",
    "GRAPH_MCP_TENANT_ID": "<directory-tenant-id>"
  }
}

このブロックを記述する場所と、その周囲のキーの名前はクライアントによって異なります。

クライアント	設定ファイル	キー
VS Code	.vscode/mcp.json（ワークスペース）、またはMCP: ユーザー設定を開く	servers
Claude Code	claude mcp add … — 編集するファイルはありません	—
Claude Desktop	macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json	mcpServers
Cursor	.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）	mcpServers
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers
MCP Inspector	コマンドライン、-e フラグ	—

初回のサインインではブラウザーが開き、MFA や条件付きアクセスを含む通常の Microsoft 365 SSO が行われます。認証結果は~/.ms-graph-mcp/token_cache.jsonにキャッシュされ、所有者のみが読み取れるため、再度プロンプトが表示されることはありません。

VS Code

{
  "inputs": [
    { "id": "clientId", "type": "promptString", "description": "Entra application (client) ID" },
    { "id": "tenantId", "type": "promptString", "description": "Entra directory (tenant) ID" }
  ],
  "servers": {
    "ms-graph": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
      "env": {
        "GRAPH_MCP_CLIENT_ID": "${input:clientId}",
        "GRAPH_MCP_TENANT_ID": "${input:tenantId}"
      }
    }
  }
}

ウィンドウを再読み込みします。VS Code で2つの ID の入力を一度求められ、その値は記憶されるため、このファイルは安全にコミットできます。チャットビューを開き、エージェントモードに切り替えると、上のスクリーンショットにあるパネルのツールピッカーにツールが表示されます。接続できない場合は、MCP: List Serversを実行して状態と出力を確認します。

Claude Code

claude mcp add ms-graph \
  --env GRAPH_MCP_CLIENT_ID=<application-client-id> \
  --env GRAPH_MCP_TENANT_ID=<directory-tenant-id> \
  -- uvx --from ms-graph-mcp ms-graph-mcp

Claude Code 内で/mcpを実行して確認します。サーバーとそのツールが一覧表示されます。

Claude Desktop

{
  "mcpServers": {
    "ms-graph": {
      "command": "uvx",
      "args": ["--from", "ms-graph-mcp", "ms-graph-mcp"],
      "env": {
        "GRAPH_MCP_CLIENT_ID": "<application-client-id>",
        "GRAPH_MCP_TENANT_ID": "<directory-tenant-id>"
      }
    }
  }
}

Claude Desktop をウィンドウを閉じるだけでなく完全に終了し、再起動して、コンポーザーにツールアイコンが表示されているか確認します。

Cursor と Windsurf

どちらも、上の表に記載されたファイルで、Claude Desktop と同じmcpServers形式を使用します。

MCP Inspector

クライアントとは独立してサーバーを確認する最も手早い方法です。

npx @modelcontextprotocol/inspector \
  uvx --from ms-graph-mcp ms-graph-mcp \
  -e GRAPH_MCP_CLIENT_ID=<application-client-id> \
  -e GRAPH_MCP_TENANT_ID=<directory-tenant-id>

Node 22.19 以降が必要です。ブラウザー UI が開き、ツールの一覧表示や手動での呼び出しができます。クライアントの問題を疑う前に試してみる価値があります。スクリプトから実行できる--cliモードもあります。詳しくはdocs/testing.mdをご覧ください。

変数はシェルから渡すのではなく、-eで渡してください。 Inspector は起動するサーバーに環境変数を渡さないため、GRAPH_MCP_CLIENT_ID=… npx @modelcontextprotocol/inspector …を実行しても、クライアント ID がない状態でサーバーが起動します。-eフラグはサーバーコマンドの後に指定してください。

代わりにソースから実行する

上記と同じブロックで、コマンドと引数をクローンしたリポジトリの絶対パスに置き換えます。

"command": "uv",
"args": ["run", "--directory", "/Users/you/workspace/ms-graph-mcp", "ms-graph-mcp"]

ここで注意が必要な点が2つあります。

uv がクライアントの PATH に含まれている必要があります。 Finder や Dock から起動した GUI アプリはシェルの PATH を引き継がないため、クライアントがわかりにくいエラーを出してサーバーの起動に失敗することがあります。その場合は、"command" に単独の名前ではなく、which uv の出力を指定してください。

--directory は省略できません。 指定しないと、uv run はクライアントが起動されたディレクトリを基準に解決しますが、そこはプロジェクトのディレクトリではありません。

うまく動作しない場合

docs/troubleshooting.mdでは、Entra のエラー、条件付きアクセス、企業の TLS プロキシ、そしてほとんどの場合はクライアントが隠している起動エラーである「server disconnected」について説明しています。

設定

2つの設定を行えば実行できます。それ以外はすべて適切なデフォルト値が設定されています。

環境変数	目的
GRAPH_MCP_CLIENT_ID	Entra アプリケーション（クライアント）IDです。対話型サインインを有効にします。
GRAPH_MCP_TENANT_ID	Entra ディレクトリ（テナント）IDです。デフォルトは common です。
GRAPH_MCP_SCOPES	要求する委任スコープをカンマ区切りで指定します。デフォルトでは読み取り専用のセットが設定されています。
GRAPH_MCP_TOOLSETS	公開するツールプロファイルを指定します。デフォルトは core です。以下を参照してください。
GRAPH_MCP_WRITE_SCOPE	書き込みツール23個を公開するには true を指定します。デフォルトでは無効です。
GRAPH_MCP_READ_ONLY	デプロイから書き込み層を完全に削除するには true を指定します。
GRAPH_MCP_LOG_LEVEL	INFO を指定すると、Graph のすべての呼び出しを stderr に記録します。デフォルトは WARNING です。

すべての設定、2種類のデプロイ形式、ホスト型／OBO のオプションについては、 docs/configuration.mdを参照してください。 サービスとして実行する方法については、 docs/hosting.mdを参照してください。

ツールセットのプロファイル

85個のツールをモデルに提示するのは多すぎます。GRAPH_MCP_TOOLSETS で名前付きプロファイルを選択できます。各プロファイルは複数の名前空間で構成されています。

プロファイル	名前空間	読み取りツール	およそのトークン数
core (デフォルト)	search, mail, calendar, files, people	23	~4,200
mail	mail	5	~800
calendar	calendar	6	~1,500
meetings	meetings, calendar	13	~2,900
files	files	6	~900
chat	chat	7	~1,000
people	people	5	~750
directory	directory, people	12	~1,900
tasks	tasks	5	~830
notes	notes	4	~570
search	search	1	~290
all	すべて	53	~9,200

カンマで区切って組み合わせます。

GRAPH_MCP_TOOLSETS=mail,calendar,tasks

デフォルトは core なので、指定しない限り公開されないツールがあります。 Teams チャット、Planner、OneNote、会議のトランスクリプト、またはディレクトリ検索を利用する場合は、該当するプロファイルを指定するか、GRAPH_MCP_TOOLSETS=all を設定してすべてを公開してください。

HTTP 経由では、呼び出し側が X-Toolsets を送信して、1回のリクエストに限り対象をさらに絞り込めます。絞り込みのみ可能です。 起動時の値が上限となるため、クライアントが all を要求しても、デプロイ時に有効にしていないツールは利用できません。これは表示対象を絞るものであり、権限を制限するものではありません。実際に呼び出しを制限するのは、書き込みスコープと内部層のゲートです。

ツールの構成

3 つの階層、1 つの認証境界です。

階層	数	公開される条件	例
読み取り	53	常時	calendar_list_upcoming_events、mail_search、meetings_get_transcript、files_search、search_query
書き込み	23	X-Write-Scope: true	mail_send、calendar_create_event、files_create_sharing_link、tasks_complete_todo
内部	9	X-Internal-Scope: true、マシンプリンシパルのみ	graph_request のパススルー、ドライブの走査／アップロード、メッセージの添付ファイル、アプリ専用の probe_graph_access

内部階層はエージェント向けのインターフェイスには含まれません。モデルにはエージェントから利用できるツールが 76 個表示されます。 名前空間別：mail 11 · tasks 11 · calendar 10 · files 10 · chat 8 · directory 7 · meetings 7 · people 6 · notes 5 · search 1。

ツール名は Microsoft 製品ではなく、Graph のアクセス許可ファミリーごとに名前空間が分けられています。実際の質問は製品の境界をまたぐためです。たとえば files_ は OneDrive と SharePoint のドキュメントライブラリの両方を扱います。これらは内部では同じ driveItem リソースだからです。

各ツールは MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint）を宣言しているため、クライアントは確認が必要な操作を把握できます。また、各ツールの説明には必要な委任アクセス許可が記載されています。

0.2.0 で名前を変更しました。 0.2.0 より前のすべてのツール名はエイリアスとして引き続き動作し、0.4.0 まで利用できます。エイリアスは tools/call では受け付けられますが、tools/list では公開されないため、コンテキストを消費しません。

ドキュメント

検索可能なサイトとして公開されています：https://nitinksingh.com/ms-graph-mcp/。

ドキュメントサイト	以下のすべての内容を検索でき、相互にリンクしています
docs/configuration.md	環境変数の一覧。デプロイ形態ごとに分類しています
docs/permissions.md	各ツールに必要な委任アクセス許可と、コピーして使える同意設定の一覧
docs/hosting.md	Streamable HTTP、ヘッダー、Docker、GHCR
docs/troubleshooting.md	Entra のエラー、Conditional Access、企業向け TLS プロキシ
docs/debugging.md	ログ、エラーコード、実際によく発生する認証エラー
docs/graph-coverage.md	Graph v1.0 の対象範囲、対象外の内容、適用範囲外の内容
docs/roadmap.md	未完了の項目
docs/testing.md	テストスイートの実行方法と構成、MCP Inspector
CONTRIBUTING.md	開発環境のセットアップ、ツール追加のチェックリスト、テストで適用される不変条件
SECURITY.md	脆弱性の報告方法と、localhost の外部に公開する前に変更すべき内容
CHANGELOG.md	リリース履歴
CLAUDE.md	アーキテクチャと、見落としやすい注意点。コーディングエージェントと新しい貢献者のどちらにも役立ちます

今後の予定

最大の不足項目は SharePoint サイトとリストです。次に、ディレクトリ機能の補完、ファイルの移動／削除、メールの下書きに対応する予定です。ソブリンクラウド（GCC High／21Vianet）は現在サポートされていません。全項目と、意図的に対象外としている内容については、 docs/roadmap.mdをご覧ください。

サポートを受ける

• セットアップとアプリ登録に関する質問 → ディスカッション
• バグ → Issue。ターミナルでサーバーを実行したときの出力を添えてください
• セキュリティの脆弱性 → 公開 Issue として報告しないでください。SECURITY.mdをご覧ください

いずれにもアクセストークン、クライアントシークレット、共有シークレットを貼り付けないでください。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdから始めてください。参加にあたっては行動規範が適用されます。

uv sync
uv run pytest -q            # full suite, offline, about two seconds
uv run ruff check .
uv run ruff format .

ライセンス

MIT — LICENSEをご覧ください。