ms-365-mcp服务器
微软365 MCP服务器
用于通过Graph与Microsoft 365和Microsoft Office服务交互的模型上下文协议（MCP）服务器 API
支持的云
此服务器支持多种Microsoft云环境：
| 云 | 描述 | 验证端点 | 图形API端点 |
|---|---|---|---|
| 全球 （默认） | 国际Microsoft 365 | login.Microsoft.com/graph.Microsoft.com | |
| 中国 （世纪互联） | 世纪互联运营的微软365 | 登录chinacloudapi.cn | 微软中国 |
先决条件
- Node.js>=20（推荐）
- Node.js 14+可能会出现依赖警告
特性
- 通过Microsoft身份验证库（SCL）进行身份验证
- 全面的Microsoft 365服务集成
- 只读模式支持安全操作
- 用于精细访问控制的工具过滤
输出格式：JSON与TOON
服务器支持两种可全局配置的输出格式：
JSON格式（默认）
标准JSON输出，打印效果很好：
{
"value": [
{
"id": "1",
"displayName": "Alice Johnson",
"mail": "alice@example.com",
"jobTitle": "Software Engineer"
}
]
}（实验）TOON格式
面向令牌的对象表示法 为了高效使用LLM令牌：
value[1]{id,displayName,mail,jobTitle}:
"1",Alice Johnson,alice@example.com,Software Engineer优点：
- 与JSON相比，令牌减少30-60%
- 最适合统一数组数据（电子邮件、日历事件、文件等列表）
- 非常适合大规模的成本敏感型应用
用途： （实验性）全局启用TOON格式：
通过CLI标志：
npx @softeria/ms-365-mcp-server --toon通过克劳德桌面配置：
{
"mcpServers": {
"ms365": {
"command": "npx",
"args": ["-y", "@softeria/ms-365-mcp-server", "--toon"]
}
}
}通过环境变量：
MS365_MCP_OUTPUT_FORMAT=toon npx @softeria/ms-365-mcp-server支持的服务和工具
该服务器提供了200多个工具，涵盖了Microsoft Graph API表面的大部分内容。每个工具将1对1映射到Graph API端点，并在中以声明方式定义 src/endpoints.json.
个人帐户工具（默认可用）
电子邮件（Outlook）、日历、OneDrive文件、Excel、OneNote、待办事项、计划、联系人、用户配置文件、搜索
组织帐户工具（需要--org模式标志）
团队和聊天、在线会议、成绩单和录音、考勤报告、SharePoint网站和列表、共享邮箱和日历、用户管理、状态、虚拟活动
所需的图形API权限
根据启用的工具动态请求权限。使用 --list-permissions 要查看配置的确切权限：
# Personal mode (default)
npx @softeria/ms-365-mcp-server --list-permissions
# Organization mode (includes Teams, SharePoint, etc.)
npx @softeria/ms-365-mcp-server --org-mode --list-permissions
# Filtered by preset
npx @softeria/ms-365-mcp-server --preset mail --list-permissions这对于部署新版本之前必须预先批准并提交Graph API权限的企业环境非常有用。
组织/工作模式
要访问工作/学校功能（团队、SharePoint等），请使用以下任何标志启用组织模式：
{
"mcpServers": {
"ms365": {
"command": "npx",
"args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode"]
}
}
}必须从一开始就启用组织模式才能访问工作帐户功能。没有这面旗帜，只有个人 帐户功能（电子邮件、日历、OneDrive等）可用。
共享邮箱访问
要访问共享邮箱，您需要：
- 组织模式：共享邮箱工具需要
--org-mode标志（仅限工作/学校帐户） - 委托权限:
Mail.Read.Shared或Mail.Send.Shared范围 - Exchange权限：必须已授予登录用户访问共享邮箱的权限
- 用法：使用共享邮箱的电子邮件地址作为
user-id共享邮箱工具中的参数
查找共享邮箱：使用 list-users 用于发现您的帐户中的可用用户和共享邮箱的工具 组织。
例子： list-shared-mailbox-messages 随着 user-id 着手 shared-mailbox@company.com
快速入门示例
在Claude Desktop中测试登录：
示例
集成
克劳德桌面版
要将此MCP服务器添加到Claude Desktop，请在“设置”>“开发人员”下编辑配置文件。
个人账户（MSA）
{
"mcpServers": {
"ms365": {
"command": "npx",
"args": ["-y", "@softeria/ms-365-mcp-server"]
}
}
}工作/学校账户（全球）
{
"mcpServers": {
"ms365": {
"command": "npx",
"args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode"]
}
}
}工作/学校账户（中国世纪互联）
{
"mcpServers": {
"ms365-china": {
"command": "npx",
"args": ["-y", "@softeria/ms-365-mcp-server", "--org-mode", "--cloud", "china"]
}
}
}克劳德代码CLI
个人账户（MSA）
claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server工作/学校账户（全球）
# macOS/Linux
claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server --org-mode
# Windows (use cmd /c wrapper)
claude mcp add ms365 -s user -- cmd /c "npx -y @softeria/ms-365-mcp-server --org-mode"工作/学校账户（中国世纪互联）
# macOS/Linux
claude mcp add ms365-china -- npx -y @softeria/ms-365-mcp-server --org-mode --cloud china
# Windows (use cmd /c wrapper)
claude mcp add ms365-china -s user -- cmd /c "npx -y @softeria/ms-365-mcp-server --org-mode --cloud china"对于支持MCP的其他接口，请参阅其各自的文档以了解正确的 整合方法。
打开WebUI
Open WebUI通过OAuth 2.1通过HTTP传输支持MCP服务器。
- 以HTTP模式启动服务器：
npx @softeria/ms-365-mcp-server --http- 在Open WebUI中，转到 管理设置→ Tools (
/admin/settings/tools) → 添加连接:
- 类型：MCP流式HTTP - 统一资源定位符：您的MCP服务器URL /mcp 路径 - 认证：OAuth 2.1
- 点击 注册客户端.
备注：默认情况下，在HTTP模式下启用动态客户端注册。使用 --no-dynamic-registration 禁用它。如果使用自定义Azure Entra应用程序，请在“移动和桌面应用程序”平台（而不是“单页应用程序”）下添加您的重定向URI。快速测试设置 使用默认的Azure应用程序（ID ms-365 和 localhost:8080 已预先配置）：
docker run -d -p 8080:8080 \
-e WEBUI_AUTH=false \
-e OPENAI_API_KEY \
ghcr.io/open-webui/open-webui:main
npx @softeria/ms-365-mcp-server --http然后添加带有URL的连接 http://localhost:3000/mcp 和ID ms-365.
在Docker中运行反向代理？ 集 --public-url https://your-domain.com 因此，可以从容器网络外部访问传递给用户浏览器的OAuth授权URL。请参阅 docs/deployment.md 完整的指南。本地开发
对于本地开发或测试：
# From the project directory
claude mcp add ms -- npx tsx src/index.ts --org-mode或者手动配置Claude Desktop：
{
"mcpServers": {
"ms365": {
"command": "node",
"args": ["/absolute/path/to/ms-365-mcp-server/dist/index.js", "--org-mode"]
}
}
}备注：运行npm run build在代码更改以更新后dist/文件夹。
认证
⚠️ 在使用工具之前，您必须进行身份验证。
服务器支持三种身份验证方法：
1.设备代码流（默认）
通过设备代码进行交互式身份验证：
- MCP客户端登录:
- 打电话给 login 工具（自动检查现有令牌） - 如果需要，获取URL+代码，在浏览器中访问 - 使用 verify-login 工具确认
- CLI登录:
npx @softeria/ms-365-mcp-server --login按照终端中的URL和代码提示进行操作。
令牌安全地缓存在您的操作系统凭据存储中（回退到文件）。
2.OAuth授权代码流（仅限HTTP模式）
跑步时 --http，服务器 需要 OAuth身份验证：
npx @softeria/ms-365-mcp-server --http 3000此模式：
- 向MCP客户端宣传OAuth功能
- 在以下位置提供OAuth端点
/auth/*（授权、令牌、元数据） - 需要
Authorization: Bearer对于所有MCP请求 - 使用Microsoft Graph API验证令牌
- 使伤残 默认情况下登录/注销工具（使用
--enable-auth-tools使他们）
MCP客户端在看到广告功能时将自动处理OAuth流。
为OAuth测试设置Azure AD
要使用OAuth模式和自定义Azure凭据（建议用于生产），您需要设置Azure AD应用程序 注册：
- 创建Azure AD应用程序注册:
- 首选 Azure 门户
- 导航到Azure Active Directory→ 应用程序注册→ 新注册
- 集合名称：“MS365 MCP服务器”
- 配置重定向URI:
- 配置OAuth回调URI：转到您的应用程序注册，然后在左侧转到身份验证。
- 在平台配置下：
- 单击添加平台（如果您还没有看到“移动和桌面应用程序”/“公共客户端”的平台）。 - 选择移动和桌面应用程序或公共客户端/本地（移动和桌面）（标签取决于门户版本）。
- MCP检验员测试(
npm run inspector):
- 转到您的应用程序注册，然后在左侧转到身份验证。
- 在平台配置下：
- 单击添加平台（如果您还没有看到“Web”平台）。 - 选择Web。 - 配置以下重定向URI - http://localhost:6274/oauth/callback - http://localhost:6274/oauth/callback/debug - http://localhost:3000/callback （可选，用于服务器回调）
- 获取凭据:
- 复制 应用程序（客户端）ID 从概述页面
- 转到证书和机密→ 新客户机密→ 复制机密值（公共应用程序可选）
- 配置环境变量:
创建一个 .env 项目根目录中的文件：
MS365_MCP_CLIENT_ID=your-azure-ad-app-client-id-here
MS365_MCP_CLIENT_SECRET=your-secret-here # Optional for public apps
MS365_MCP_TENANT_ID=common配置这些后，服务器将使用您的自定义Azure应用程序，而不是内置应用程序。
3.自带代币（BYOT）
如果您将ms-365-mcp-server作为外部管理Microsoft OAuth令牌的较大系统的一部分运行，则可以 直接向此MCP服务器提供访问令牌：
MS365_MCP_OAUTH_TOKEN=your_oauth_token npx @softeria/ms-365-mcp-server这种方法：
- 绕过交互式身份验证流程
- 将预先存在的OAuth令牌用于Microsoft Graph API请求
- 不处理令牌刷新（令牌生命周期管理由您负责）
备注：HTTP模式需要身份验证。对于未经身份验证的测试，使用设备代码流的stdio模式。 身份验证工具：在HTTP模式下，默认情况下禁用登录/注销工具，因为OAuth处理身份验证。 使用 --enable-auth-tools 如果你需要的话。多账户支持
使用单个服务器实例为多个Microsoft帐户提供服务。当登录多个帐户时 account 参数会自动注入到每个工具中，允许您指定每次工具调用使用哪个帐户。
登录多个帐户 （每个账户一次）：
# Login first account (device code flow)
npx @softeria/ms-365-mcp-server --login
# Follow the device code prompt, sign in as personal@outlook.com
# Login second account
npx @softeria/ms-365-mcp-server --login
# Follow the device code prompt, sign in as work@company.com列出已配置的帐户：
npx @softeria/ms-365-mcp-server --list-accounts在工具调用中使用： 通过 "account": "work@company.com" 在任何工具请求中：
{ "tool": "list-mail-messages", "arguments": { "account": "work@company.com" } }行为：
- 带着一个 单一账户 配置后，它会自动选择（否
account所需参数）。 - 随着 多个账户 而没有
account参数，服务器使用所选的默认值或返回一个有用的错误，列出可用帐户。 - 100%向后兼容：现有的单一帐户设置保持不变。
- 这
account参数接受电子邮件地址（例如。user@outlook.com)或手写homeAccountId.
对于MCP多路复用器（Legate、Governor）： 多账户模式取代了N流程模式。单个实例通过以下方式处理所有帐户，而不是为每个帐户生成一个服务器 account 参数，将刀具重复从N×110减少到110。工具预设
为了减少初始连接开销，请使用预设的工具类别，而不是加载所有90多个工具：
npx @softeria/ms-365-mcp-server --preset mail
npx @softeria/ms-365-mcp-server --list-presets # See all available presets可用预设： mail, calendar, files, personal, work, excel, contacts, tasks, onenote, search, users, all
动态工具发现
与其预先加载所有90多个工具，不如使用动态发现，这样LLM只在需要时才查找和加载工具：
npx @softeria/ms-365-mcp-server --discovery保持初始上下文较小，并减少令牌使用，特别适用于长时间会话或成本敏感设置（例如，针对付费API运行Open WebUI）。
CLI选项
直接从命令行运行ms-365-mcp-server时，可以使用以下选项：
--login Login using device code flow
--logout Log out and clear saved credentials
--verify-login Verify login without starting the server
--list-permissions List all required Graph API permissions and exit (respects --org-mode, --preset, --enabled-tools)
--org-mode Enable organization/work mode from start (includes Teams, SharePoint, etc.)
--work-mode Alias for --org-mode
--force-work-scopes Backwards compatibility alias for --org-mode (deprecated)
--cloud Microsoft cloud environment: global (default) or china (21Vianet)服务器选项
当作为MCP服务器运行时，可以使用以下选项：
-v Enable verbose logging
--read-only Start server in read-only mode, disabling write operations
--http [port] Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
Starts Express.js server with MCP endpoint at /mcp
--enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
--no-dynamic-registration Disable OAuth Dynamic Client Registration (enabled by default in HTTP mode)
--enabled-tools
Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)
--preset Use preset tool categories (comma-separated). See "Tool Presets" section above
--list-presets List all available presets and exit
--toon (experimental) Enable TOON output format for 30-60% token reduction
--discovery Dynamic tool discovery: loads tools on demand to reduce initial token usage (see "Dynamic Tool Discovery" above)
--public-url Public base URL for OAuth when behind a reverse proxy (see Open WebUI section and docs/deployment.md)环境变量：
READ_ONLY=true|1：替代--只读标志ENABLED_TOOLS：使用正则表达式模式过滤工具（替代启用的工具标志）MS365_MCP_ORG_MODE=true|1：启用组织/工作模式（替代--org模式标志）MS365_MCP_FORCE_WORK_SCOPES=true|1：MS365_MCP_ORG_MODE的向后兼容性MS365_MCP_OUTPUT_FORMAT=toon：启用TOON输出格式（替代--TOON标志）MS365_MCP_MAX_TOP=：Graph的硬上限$top/top列表请求（正整数）。当模型传递一个更大的值时，服务器会将其钳制到n因此，响应保持较小。例子：MS365_MCP_MAX_TOP=15MS365_MCP_BODY_FORMAT=html：将电子邮件正文作为HTML而不是纯文本返回（默认值：文本）MS365_MCP_CLOUD_TYPE=global|china：Microsoft云环境（替代--cloud标志）LOG_LEVEL：设置日志记录级别（默认值：“info”）SILENT=true|1：禁用控制台输出MS365_MCP_CLIENT_ID：自定义Azure应用程序客户端ID（默认为内置应用程序）MS365_MCP_TENANT_ID：自定义租户ID（多租户默认为“公共”）MS365_MCP_OAUTH_TOKEN：Microsoft Graph API的预存在OAuth令牌（BYOT方法）MS365_MCP_KEYVAULT_URL：用于机密管理的Azure密钥库URL（请参阅Azure密钥库部分）MS365_MCP_TOKEN_CACHE_PATH：自定义的文件路径，用于存储标签缓存（请参阅下面的标签存储）MS365_MCP_SELECTED_ACCOUNT_PATH：所选帐户元数据的自定义文件路径（请参阅下面的令牌存储）
令牌存储
身份验证令牌在可用时使用操作系统凭据存储（通过keytar）进行存储。如果未安装keytar或发生故障（在无头Linux上很常见），服务器将回退到基于文件的存储。
默认回退路径 相对于已安装的包目录。这意味着当通过npm重新安装或更新包时，令牌可能会丢失。
要在更新之间持久化令牌，请在包目录外设置自定义路径：
export MS365_MCP_TOKEN_CACHE_PATH="$HOME/.config/ms365-mcp/.token-cache.json"
export MS365_MCP_SELECTED_ACCOUNT_PATH="$HOME/.config/ms365-mcp/.selected-account.json"父目录是自动创建的。文件是用 0600 权限。
安全说明：基于文件的令牌存储将敏感凭据写入磁盘。确保所选目录具有适当的访问控制。如果可用，最好使用操作系统凭据存储（keytar）。
托管/沙盒环境 （例如，人类协作）：设置MS365_MCP_TOKEN_CACHE_PATH和MS365_MCP_SELECTED_ACCOUNT_PATH为了使令牌在会话之间持续存在，需要将令牌设置为持久挂载。
Azure密钥库集成
对于生产部署，您可以将机密存储在Azure密钥库中，而不是环境变量中。这对于具有托管身份的Azure容器应用程序特别有用。
设置
- 创建密钥库 （如果你没有）：
az keyvault create --name your-keyvault-name --resource-group your-rg --location eastus- 将机密添加到密钥库:
az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-id --value "your-client-id"
az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-tenant-id --value "your-tenant-id"
# Optional: if using confidential client flow
az keyvault secret set --vault-name your-keyvault-name --name ms365-mcp-client-secret --value "your-secret"- 授予对密钥库的访问权限:
对于具有托管身份的Azure容器应用程序：
# Get the managed identity principal ID
PRINCIPAL_ID=$(az containerapp show --name your-app --resource-group your-rg --query identity.principalId -o tsv)
# Grant access to Key Vault secrets
az keyvault set-policy --name your-keyvault-name --object-id $PRINCIPAL_ID --secret-permissions get list对于使用Azure CLI进行本地开发：
# Your Azure CLI identity already has access if you have appropriate RBAC roles
az login- 配置服务器:
MS365_MCP_KEYVAULT_URL=https://your-keyvault-name.vault.azure.net npx @softeria/ms-365-mcp-server秘密名称映射
| 密钥库密码名称 | 环境变量 | 必填 |
|---|---|---|
| ms365 mcp客户端id | ms365_mcp_client_id | 是 |
| ms365 mcp租户id | ms365_mcp_tenant_id | 否（默认为“通用”） |
| ms365 mcp客户端机密 | ms365_mcp_client_secret | 否 |
认证
密钥库集成使用 DefaultAzureCredential Azure Identity SDK会自动按顺序尝试多种身份验证方法：
- 环境变量（AZURE_CLIENT_ID、AZURE_CLEENT_CRET、AZURE_TENANT_ID）
- 托管身份（建议用于Azure容器应用程序）
- Azure CLI凭据（用于本地开发）
- Visual Studio代码凭据
- Azure PowerShell凭据
可选依赖关系
Azure密钥库包(@azure/identity 和 @azure/keyvault-secrets)是可选的依赖关系。它们仅在以下情况下加载 MS365_MCP_KEYVAULT_URL 已配置。如果不使用密钥库，则不需要这些软件包。
生产部署
看 docs/deployment.md 获取托管服务器以供组织范围访问的完整指南，包括Docker、Azure容器应用程序、Azure应用服务、Azure AD应用程序注册、反向代理设置、客户端配置和公开端点。
贡献
我们欢迎捐款！在提交pull请求之前，请确保您的更改符合我们的质量标准。
运行验证脚本以检查所有代码质量要求：
npm run verify对于开发者
克隆存储库后，您可能需要根据Microsoft Graph OpenAPI规范生成客户端代码：
npm run generate支持
如果您遇到问题或需要帮助：
许可证
麻省理工学院© 2026 软件