ms-graph-mcp

ms-graph-mcp

Releases · 更新日志

一个用于 Microsoft Graph 的 Model Context Protocol 服务，提供 85 个 工具，涵盖邮件、日历、会议（包括文字记录）、Teams 聊天、文件、SharePoint、 搜索、人员、联系人、目录、任务和 OneNote，支持 stdio 或 Streamable HTTP。

使用你自己的 Microsoft 账户登录——通过浏览器 SSO，无需粘贴令牌，也无需客户端密钥。

• 不使用 msgraph-sdk 或 azure-identity——Graph 客户端基于原生 httpx2，因此依赖树 更精简，且可检查线上的行为。
• 强制执行读写分离，而非仅作建议——除非调用方明确选择启用，否则写入工具既会被隐藏，也会被拒绝。
• 默认与身份验证方式无关——工具通过请求上下文接收已获取的 Graph 令牌。服务器也可以自行执行 代表用户的令牌交换，让你按需将其用作正规的 OAuth 资源服务器。

状态：早期版本。 从一个生产环境中的 Agent 平台提取而来，并已在真实租户上运行。代码经过实战检验；打包方式和公共 API 则较新。在 1.0 之前，配置项可能会有所变动。

安装

需要 Python 3.12+。有两种方式——根据你的用途选择。

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

然后使用下方配置 MCP 客户端中的源代码配置。

设置 Entra 应用

你需要注册一个 Entra ID 应用，大约需要两分钟。不要创建客户端密钥： 此处注册的是 公共客户端，它会通过 PKCE 在浏览器中为你登录。在你自己的机器上运行的程序，其密钥会被任何能读取配置文件的人看到，因此设计这种流程时就不需要密钥。配置文件中只会包含两个 ID，二者都不敏感。

在 Entra 门户 → 应用注册 → 新注册：

• 名称： 任意名称，例如 ms-graph-mcp
• 支持的帐户类型： 仅此组织目录中的帐户
• 重定向 URI： 选择 公共客户端/本机，值为 http://localhost

不必操作 证书和机密，你不需要其中的任何内容。

然后，在新建的应用中：

• 身份验证 → 启用 允许公共客户端流

• API 权限 → 添加权限 → Microsoft Graph → 委托权限，添加你希望 Agent 访问的权限。一个合适的只读起始权限集：

  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 客户端都需要相同的三项内容：命令、参数和环境变量块：

{
  "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: Open User Configuration	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 标志	—

首次登录时，浏览器会打开并使用常规的 Microsoft 365 SSO 登录，包括 MFA 和条件访问。登录结果会缓存在 ~/.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 会提示你输入这两个 ID 一次，并记住它们，因此可以安全地提交此文件。打开聊天视图，切换到 Agent 模式，工具便会显示在工具选择器中，也就是上方截图里的面板。通过 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+。它会打开一个浏览器界面，你可以在其中列出工具并手动调用。在归咎于客户端之前，值得先试试。它也支持可编写脚本的 --cli 模式；详见 docs/testing.md。

使用 -e 传递变量，不要从 Shell 传递。 Inspector 不会向其启动的服务提供你的环境变量，因此 GRAPH_MCP_CLIENT_ID=… npx @modelcontextprotocol/inspector … 会在没有客户端 ID 的情况下启动服务。-e 标志应放在服务命令之后。

改为从源码运行

使用与上文相同的代码块——将命令和参数替换为克隆仓库的绝对路径：

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

有两点容易让人遇到问题：

uv 必须位于客户端的 PATH 中。 从 Finder 或 Dock 启动的 GUI 应用不会继承 shell 的 PATH，因此客户端可能无法启动服务，并显示不明所以的错误。如果发生这种情况，请将 which uv 的输出填入 "command"，而不是使用裸名称。

--directory 不能省略。 如果没有它，uv run 会根据客户端启动时所在的目录进行解析，而该目录不会是项目目录。

遇到问题了？

docs/troubleshooting.md 介绍了 Entra 错误、Conditional Access、企业 TLS 代理，以及几乎总是客户端隐藏了启动错误所导致的“server disconnected”问题。

配置

设置两个选项即可运行；其他选项都有可用的默认值。

环境变量	用途
GRAPH_MCP_CLIENT_ID	Entra 应用程序（客户端）ID。启用交互式登录。
GRAPH_MCP_TENANT_ID	Entra 目录（租户）ID。默认为 common。
GRAPH_MCP_SCOPES	以逗号分隔的要请求的委派权限范围。默认为只读权限集。
GRAPH_MCP_TOOLSETS	要公开的工具配置集。默认为 core。见下文。
GRAPH_MCP_WRITE_SCOPE	设为 true 以公开 23 个写入工具。默认关闭。
GRAPH_MCP_READ_ONLY	设为 true 可从部署中彻底移除写入层。
GRAPH_MCP_LOG_LEVEL	INFO 会将每次 Graph 调用记录到 stderr。默认为 WARNING。

所有设置、两种部署方式，以及托管/OBO 选项均见 docs/configuration.md。 如需将其作为服务运行，请参阅 docs/hosting.md。

工具集配置集

85 个工具对于模型来说数量不少。GRAPH_MCP_TOOLSETS 可选择具名配置集，每个配置集由一组命名空间组成：

配置集	命名空间	读取工具	约计 token 数
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，进一步缩小单次请求的范围。它只能缩小范围。 启动时的设置构成上限，因此客户端请求 all 也无法获得部署未启用的功能。这只会筛选可见性，不会限制权限——真正阻止调用的是写入权限范围和内部层级门控。

工具范围

三个层级，共用一个身份验证接口。

层级	数量	暴露条件	示例
读取	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

内部层级不属于 Agent 工具范围。模型可见 76 个 Agent 工具。 按命名空间划分：mail 11 · tasks 11 · calendar 10 · files 10 · chat 8 · directory 7 · meetings 7 · people 6 · notes 5 · search 1。

工具名称按 Graph 权限系列划分，而非按 Microsoft 产品划分，因为实际问题会跨越产品边界——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 错误、条件访问、企业 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	架构和不易察觉的陷阱，供编码 Agent 和新贡献者参考

接下来

SharePoint 站点和列表是最大的缺口；目录功能补全、文件移动/删除和邮件草稿将随后实现。目前不支持主权云（GCC High / 21Vianet）。完整列表以及明确不在范围内的内容，请参阅 docs/roadmap.md。

获取帮助

• 设置和应用注册问题 → 讨论区
• 错误 → 问题，并附上在终端中运行 服务的输出
• 安全漏洞 → 切勿公开提交问题；请参阅 SECURITY.md

切勿在其中粘贴访问令牌、客户端密钥或共享密钥。

参与贡献

欢迎提交问题和拉取请求。请先阅读 CONTRIBUTING.md； 参与者须遵守 行为准则。

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

许可证

MIT — 请参阅 LICENSE。