Softeria/ms-365-mcp-server

A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph API

📦 ms-365-mcp-server 是什么？

一个 Node-JS 服务器，将 Microsoft 365 (Graph) 功能作为 Model-Context-Protocol (MCP) 工具暴露。每个工具映射到一个 Graph API 端点（例如 list-mail-messages、get-drive-item），并可由 Claude Desktop、Claude Code CLI 或任何其他 MCP 兼容的前端等 LLM 驱动的助手调用。

🎯 核心目的

将庞大的 Microsoft 365 Graph 接口转换为 稳定、声明式的工具集，使 LLM 无需编写自定义 HTTP 代码即可调用。
提供 两种输出编码 – 常规 JSON（默认）和实验性的 TOON 格式，后者可将列表式数据的令牌数量减少 30-60%。
支持个人和组织（工作/学校）账户、多个云（全球及中国），以及从单个服务器实例进行 多账户 使用。

⚙️ 主要功能（如 README 所述）

功能	为您提供什么
认证	基于 MSAL 的设备代码流（默认）、在 `--http` 模式下运行时使用 OAuth 2.1，或通过 `MS365_MCP_OAUTH_TOKEN` 自带令牌。
工具表面	300 多个自动生成的工具，覆盖完整的 Graph API（邮件、日历、OneDrive、Teams、SharePoint、Planner 等）。
预设与过滤	`--preset`、`--enabled-tools` 正则表达式或 `--allowed-scopes` 允许您将工具集缩小到仅需要的部分，从而减少令牌使用量和所需权限。
只读模式	防止意外写入的安全措施（`--read-only`）。
动态权限发现	`--list-permissions` 显示当前配置将请求的确切 Graph 范围，帮助管理员预先批准同意。
输出格式	JSON（美化打印）或实验性的 TOON（Token-Oriented Object Notation），以降低 LLM 调用成本。
多账户支持	登录多个 Microsoft 账户；每次工具调用可以指定 `account` 参数（电子邮件或 MSAL homeAccountId）。
企业控制	`--allowed-scopes` 缩小令牌请求；`--extra-scopes` 添加自定义范围；SharePoint 可以限制为 `Sites.Selected`。
可通过 CLI 或 Docker 部署	使用 `npx @softeria/ms-365-mcp-server …` 运行或容器化；HTTP 模式可在反向代理后使用 `--public-url` 工作。

🛠️ 典型工作流程

安装 – npm i -g @softeria/ms-365-mcp-server（或通过 npx 运行）。
认证 – npx @softeria/ms-365-mcp-server --login（设备代码）或以 --http 模式启动以进行 OAuth。
配置 – 使用 README 中的 JSON 片段将服务器添加到您的 LLM 客户端（Claude Desktop、Claude Code CLI、Open WebUI 等）。
选择模式 – 默认为个人模式；添加 --org-mode 以解锁 Teams、SharePoint、共享邮箱等。
调用工具 – LLM 发送类似 { "tool": "list-mail-messages", "arguments": { "account": "work@company.com" } } 的请求；服务器与 Graph 通信并返回 JSON 或 TOON。

📦 安装与快速开始

# 直接运行（无需全局安装）
npx @softeria/ms-365-mcp-server --login   # 设备代码流
# 测试一个工具
npx @softeria/ms-365-mcp-server --tool list-mail-messages

对于 Docker：

docker run -p 3000:3000 ghcr.io/softeria/ms-365-mcp-server:latest --http

然后将您的 MCP 兼容客户端指向 http://localhost:3000/mcp。

🔗 提到的集成点

Claude Desktop – 在 设置 → 开发者 下添加。
Claude Code CLI – claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server …。
Open WebUI – HTTP 模式，OAuth 2.1，在 UI 中注册客户端。
自定义客户端 – 任何可以讲 MCP（通过 stdio 或 HTTP 的 JSON）的工具。

📚 何时使用它？

构建需要读取/写入用户 Outlook 邮件、日历或 OneDrive 文件的 AI 助手。
必须与 Teams 聊天、SharePoint 列表或 Planner 任务交互，同时遵守严格权限边界的企业机器人。
任何 令牌效率 重要的 LLM 驱动工作流 – 切换到 TOON 以削减大型列表响应的成本。
单个服务器实例管理许多用户的 Microsoft 账户的多租户 SaaS。

⚠️ README 中的限制/注意事项

TOON 被标记为 实验性 – 可能会更改。
在 HTTP 模式下，认证工具默认禁用；如有需要，使用 --enable-auth-tools 启用。
默认的 Softeria Azure 应用具有有限的权限集；要请求额外的范围，您必须提供自己的 Azure AD 应用（MS365_MCP_CLIENT_ID 等）。
--allowed-scopes 只能缩小权限；要扩大，您需要 --extra-scopes。
固定（MS365_MCP_EXPECTED_USERNAME / --expected-home-account-id）是可选的，但对于无头部署很有用。

📖 在哪里了解更多

源代码 – src/endpoints.json 列出了每个生成的工具。
部署指南 – docs/deployment.md（参考反向代理设置）。
TOON 格式 – 参见链接的 GitHub 仓库 github.com/toon-format/toon。

TL;DR

ms-365-mcp-server 是一个现成的桥接器，将 Microsoft 365 Graph API 转换为大型、权限感知的工具箱，LLM 可以通过 Model-Context-Protocol 调用。它处理认证、权限范围、多账户管理，甚至提供节省令牌的输出格式，使其成为构建需要真实世界 Microsoft 365 数据的 AI 助手的实用组件。