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 格式，後者可將列表式資料的 token 數量減少 30-60%。
支援個人和組織（工作/學校）帳戶、多個雲端（全球及中國），以及從單一伺服器執行個體進行 多帳戶 使用。

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

功能	為您提供什麼
驗證	基於 MSAL 的裝置代碼流（預設）、在 `--http` 模式下執行時使用 OAuth 2.1，或透過 `MS365_MCP_OAUTH_TOKEN` 自帶 token。
工具表面	300 多個自動產生的工具，涵蓋完整的 Graph API（郵件、行事曆、OneDrive、Teams、SharePoint、Planner 等）。
預設與過濾	`--preset`、`--enabled-tools` 正規表示式或 `--allowed-scopes` 允許您將工具集縮小至僅需要的部分，從而減少 token 使用量和所需權限。
唯讀模式	防止意外寫入的安全措施（`--read-only`）。
動態權限發現	`--list-permissions` 顯示目前設定將請求的確切 Graph 範圍，幫助管理員預先核准同意。
輸出格式	JSON（美化列印）或實驗性的 TOON（Token-Oriented Object Notation），以降低 LLM 呼叫成本。
多帳戶支援	登入多個 Microsoft 帳戶；每次工具呼叫可以指定 `account` 參數（電子郵件或 MSAL homeAccountId）。
企業控制	`--allowed-scopes` 縮小 token 請求；`--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 任務互動，同時遵守嚴格權限邊界的企業機器人。
任何 token 效率 重要的 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 呼叫。它處理驗證、權限範圍、多帳戶管理，甚至提供節省 token 的輸出格式，使其成為建置需要真實世界 Microsoft 365 資料的 AI 助手的實用元件。