MCP Desktop - Microsoft Cloud Platform Desktop Client

MCP Microsoft Office

一个 MCP 服务。支持多位用户。在测试租户中产生真实的 Microsoft 365 流量。

---

问题

测试租户往往空空如也。静态测试数据无法模拟真实工作流。当你需要让 Agent 发送真实邮件、安排真实会议，并在真实的 Teams 频道中协作时，模拟对象和存根就无法满足需求。

解决方案

本项目通过 Graph API，将任何兼容 MCP 的 AI 客户端连接到 Microsoft 365。每个 Agent 都以不同的租户用户身份进行身份验证，并对真实数据执行实际操作。

• 117 个工具，涵盖 12 个模块：邮件、日历、文件、Excel、Word、PowerPoint、Teams、联系人、待办事项、群组、人员、搜索
• 多用户：一个服务支持整个团队，每位用户的数据相互隔离
• 真实的 Graph API 调用：每项操作都会访问实际租户，而不是模拟环境
• 安全：令牌在静态存储时经过加密，不会将凭据存储在第三方服务上

---

架构

                    ┌──────────────────┐
                    │  MCP Client      │
                    │  (Claude, etc.)  │
                    └────────┬─────────┘
                             │ JSON-RPC (stdin/stdout)
                    ┌────────▼─────────┐
                    │  MCP Adapter     │
                    │  (runs locally)  │
                    └────────┬─────────┘
                             │ HTTP + Bearer Token
                    ┌────────▼─────────┐
                    │  MCP Server      │
                    │  (local or       │
                    │   remote)        │
                    └────────┬─────────┘
                             │ Microsoft Graph API
                    ┌────────▼─────────┐
                    │  Microsoft 365   │
                    │  (your tenant)   │
                    └──────────────────┘

由三部分组成：

1. MCP 客户端——你交互的 AI
2. MCP 适配器——一个 Node.js 进程，用于将 MCP 协议转换为 HTTP 请求（与客户端运行在同一台机器上）
3. MCP 服务——负责身份验证并调用 Microsoft Graph API（在本地或远程服务上运行）

---

权限

该服务需要 18 项 Microsoft Graph 委托权限。其中 12 项无需管理员同意即可使用，另外 6 项需要租户管理员授权。

无需管理员同意

权限	解锁的工具
User.Read	身份验证、用户个人资料
Mail.ReadWrite	readMail、readMailDetails、markEmailRead、flagMail、getMailAttachments、addMailAttachment、removeMailAttachment
Mail.Send	sendMail、replyToMail
Calendars.ReadWrite	getEvents、createEvent、updateEvent、cancelEvent、acceptEvent、tentativelyAcceptEvent、declineEvent、getAvailability、findMeetingTimes、getRooms、getCalendars、addAttachment、removeAttachment
Files.ReadWrite.All	listFiles、uploadFile、downloadFile、getFileMetadata、getFileContent、setFileContent、updateFileContent、createSharingLink、getSharingLinks、removeSharingPermission、listChannelFiles、uploadFileToChannel、readChannelFile、所有 Excel 工作簿工具、所有 Word/PowerPoint 工具
Contacts.ReadWrite	listContacts、getContact、createContact、updateContact、deleteContact、searchContacts
Tasks.ReadWrite	listTaskLists、getTaskList、createTaskList、updateTaskList、deleteTaskList、listTasks、getTask、createTask、updateTask、deleteTask、completeTask
Chat.ReadWrite	listChats、createChat、getChatMessages、sendChatMessage
Channel.ReadBasic.All	listTeamChannels、getChannelMessages
ChannelMessage.Send	sendChannelMessage、replyToMessage
Channel.Create	createTeamChannel
OnlineMeetings.ReadWrite	createOnlineMeeting、getOnlineMeeting、listOnlineMeetings、getMeetingByJoinUrl

需要管理员同意

权限	解锁的其他工具
User.Read.All	解析 Teams 中的用户 ID、搜索人员
People.Read.All	findPeople、getRelevantPeople、getPersonById
Group.Read.All	listGroups、getGroup、listGroupMembers、listMyGroups
ChannelMember.ReadWrite.All	addChannelMember
ChannelMessage.Read.All	读取频道消息历史记录
OnlineMeetingTranscript.Read.All	getMeetingTranscripts、getMeetingTranscriptContent

未获得管理员同意时，你可以使用邮件、日历、文件、Excel 工作簿、Word 文档、PowerPoint 演示文稿、联系人、待办事项、聊天和基本的 Teams 频道操作。获得管理员同意后，还可以使用人员目录搜索、群组、频道成员管理和会议转录。

---

快速开始

前置条件

• Node.js 18+（下载）
• Claude Desktop（下载）或其他 MCP 客户端
• Microsoft 365 账户（工作、学校或个人账户）

步骤 1：注册 Azure 应用

1. 前往 Azure Portal > Microsoft Entra ID > App registrations > New registration
2. 将其命名为 MCP-Microsoft-Office，并使用你偏好的账户类型注册
3. 复制 Application (client) ID 和 Directory (tenant) ID
4. 前往 API permissions > Add a permission > Microsoft Graph > Delegated permissions
5. 添加上方列出的 18 项权限
6. 如果你是租户管理员，请点击 Grant admin consent
7. 前往 Authentication > Add a platform > Web
   • 重定向 URI：http://localhost:3000/api/auth/callback
   • 启用 Allow public client flows

步骤 2：克隆并配置

git clone https://github.com/Aanerud/MCP-Microsoft-Office.git
cd MCP-Microsoft-Office
npm install

将 .env.example 复制为 .env，并填写你的 Azure 应用详情：

MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_TENANT_ID=your-tenant-id

步骤 3：启动服务并进行身份验证

npm run dev:web

在浏览器中打开 http://localhost:3000。点击 Login with Microsoft，登录并授予权限。然后点击 Generate MCP Token 并复制令牌。

步骤 4：配置 Claude Desktop

编辑 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

Claude Desktop 对每个 MCP 服务实际最多支持约 55 个工具。此项目提供 117 个工具，因此我们将其拆分到三个共用同一适配器和后端的服务中：

{
  "mcpServers": {
    "microsoft-365": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "search,mail,calendar,files,people,contacts,groups,query"
      }
    },
    "microsoft-365-teams": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "teams,todo"
      }
    },
    "microsoft-365-office": {
      "command": "node",
      "args": ["/path/to/MCP-Microsoft-Office/mcp-adapter.cjs"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_BEARER_TOKEN": "paste-your-token-here",
        "MCP_MODULES": "excel,word,powerpoint,files"
      }
    }
  }
}

MCP_MODULES 用于筛选适配器提供的模块。省略此项即可提供全部 117 个工具（适用于没有工具数量限制的客户端）。

在 env 块中设置 MCP_DEBUG=1，即可将诊断日志输出到 stderr，有助于排查工具分发问题。

重启 Claude Desktop。可以询问：“我今天的日历上有什么？” 或 “创建一个包含预算表的 Excel 工作簿。”

---

工具（117）

邮件（9）

工具	描述
readMail	读取收件箱邮件
sendMail	发送邮件
replyToMail	回复邮件
readMailDetails	获取完整邮件内容
markEmailRead	将邮件标记为已读或未读
flagMail	为邮件添加或移除标记
getMailAttachments	列出邮件附件
addMailAttachment	为邮件添加附件
removeMailAttachment	从邮件中移除附件

日历（13）

工具	描述
getEvents	获取日历事件
createEvent	创建会议或事件
updateEvent	修改现有事件
cancelEvent	取消事件
acceptEvent	接受会议邀请
tentativelyAcceptEvent	暂时接受邀请
declineEvent	拒绝会议邀请
getAvailability	查看空闲和忙碌时段
findMeetingTimes	查找合适的会议时段
getRooms	查找会议室
getCalendars	列出所有日历
addAttachment	为事件添加附件
removeAttachment	移除事件附件

文件（10）

工具	描述
listFiles	列出 OneDrive 文件
uploadFile	上传文件
downloadFile	下载文件
getFileMetadata	获取文件信息
getFileContent	读取文件内容
setFileContent	写入文件内容
updateFileContent	更新现有文件
createSharingLink	创建共享链接
getSharingLinks	列出共享链接
removeSharingPermission	移除共享访问权限

Excel（30）

直接操作存储在 OneDrive 或 SharePoint 中的 Excel 工作簿，无需下载文件。所有操作都通过 Microsoft Graph 的工作簿 API 执行，并透明地管理会话。

工具	描述
createWorkbookSession	打开工作簿会话（持久或临时）
closeWorkbookSession	关闭活动工作簿会话
listWorksheets	列出工作簿中的所有工作表
addWorksheet	添加新工作表
getWorksheet	按名称或 ID 获取工作表
updateWorksheet	重命名、调整位置或隐藏工作表
deleteWorksheet	删除工作表
getRange	读取单元格值、公式和格式
updateRange	写入单元格区域的值
getRangeFormat	获取格式（字体、填充、边框）
updateRangeFormat	设置格式（粗体、颜色、数字格式）
sortRange	对区域中的单元格排序
mergeRange	合并单元格
unmergeRange	取消合并单元格
listTables	列出工作表中的所有表格
createTable	根据区域创建表格
updateTable	重命名表格或更改其样式
deleteTable	删除表格
listTableRows	列出表格中的所有行
addTableRow	向表格添加一行
deleteTableRow	按索引删除一行
listTableColumns	列出表格中的所有列
addTableColumn	向表格添加一列
deleteTableColumn	删除一列
sortTable	按列对表格排序
filterTable	对表格列应用筛选器
clearTableFilter	清除列筛选器
convertTableToRange	将表格转换回普通区域
callWorkbookFunction	调用 300 多个 Excel 函数（SUM、VLOOKUP、PMT 等）
calculateWorkbook	重新计算所有公式

Word（5）

创建、读取和转换 Word 文档。文档根据结构化 JSON 创建并存储在 OneDrive 中。读取时会使用多库回退链：mammoth（为 .docx 生成最佳 HTML）→ word-extractor（同时处理 .doc 和 .docx）→ webUrl 回退。二进制下载使用 Graph beta /contentStream 端点，以确保可靠传输二进制内容。

工具	描述
createWordDocument	根据结构化内容（标题、段落、表格、列表、图片）创建 .docx
readWordDocument	以 HTML 和纯文本形式读取文档
getWordDocumentMetadata	获取标题、作者、日期和关键词
getWordDocumentAsHtml	将文档内容转换为 HTML
convertDocumentToPdf	将 Word 文档转换为 PDF

注意： 某些 SharePoint 租户会在 .docx 文件上传后的几秒内将其转换为 OLE2 二进制格式。发生这种情况时，客户端解析库无法读取该文件。服务器会妥善回退，返回 webUrl，以便用户在浏览器中打开文档。

PowerPoint（4）

创建、读取和转换 PowerPoint 演示文稿。演示文稿根据结构化幻灯片数据生成并存储在 OneDrive 中。读取时会使用 Graph HTML 转换，并在失败时回退到 jszip 提取每张幻灯片的文本。

工具	描述
createPresentation	创建包含标题、内容和空白幻灯片的 .pptx
readPresentation	读取幻灯片内容（每张幻灯片的文本元素）
getPresentationMetadata	获取标题、作者、幻灯片数量和日期
convertPresentationToPdf	将演示文稿转换为 PDF

Teams（21）

工具	描述
listChats	列出 Teams 聊天
createChat	创建新聊天
getChatMessages	读取聊天消息
sendChatMessage	发送聊天消息
listJoinedTeams	列出你的团队
listTeamChannels	列出团队频道
createTeamChannel	创建频道
addChannelMember	将成员添加到频道
getChannelMessages	读取频道消息
sendChannelMessage	在频道中发布消息
replyToMessage	回复频道消息
listChannelFiles	列出频道中的文件
uploadFileToChannel	将文件上传到频道
readChannelFile	读取频道文件
createOnlineMeeting	创建 Teams 会议
getOnlineMeeting	获取会议详情
listOnlineMeetings	列出在线会议
getMeetingByJoinUrl	根据加入链接查找会议
getMeetingTranscripts	获取会议转录文本
getMeetingTranscriptContent	读取转录文本内容

（注意：addChannelMember 仅适用于私人频道。标准频道会自动包含所有团队成员。）

联系人（6）

工具	描述
listContacts	列出联系人
getContact	获取联系人详情
createContact	创建联系人
updateContact	更新联系人信息
deleteContact	删除联系人
searchContacts	搜索联系人

待办事项（11）

工具	描述
listTaskLists	列出任务列表
getTaskList	获取任务列表
createTaskList	创建任务列表
updateTaskList	重命名任务列表
deleteTaskList	删除任务列表
listTasks	列出任务
getTask	获取任务详情
createTask	创建任务
updateTask	更新任务
deleteTask	删除任务
completeTask	将任务标记为已完成

群组（4）

工具	描述
listGroups	列出 Microsoft 365 群组
getGroup	获取群组详情
listGroupMembers	列出群组成员
listMyGroups	列出你的群组

人员（3）

工具	描述
findPeople	搜索目录
getRelevantPeople	获取常用联系人
getPersonById	获取人员详情

搜索（1）

工具	描述
search	跨邮件、文件、日历事件和聊天消息进行统一搜索

---

多用户

每位用户独立进行身份验证。服务会根据用户身份隔离所有数据。

  Alice ([email protected])          Bob ([email protected])
  ├─ Her own Microsoft tokens        ├─ His own Microsoft tokens
  ├─ Her own session                  ├─ His own session
  └─ Claude Desktop (her laptop)     └─ Claude Desktop (his PC)

              Complete data isolation.
         Alice never sees Bob's data.

要使用多个 Agent 进行自动化测试，请使用 ROPC（资源所有者密码凭据）流程以编程方式进行身份验证：

# Start the server
npm run dev:web

# Run the E2E test suite (authenticates 3 users via ROPC)
node tests/run-all.cjs

测试套件会对多个用户进行身份验证，然后测试 12 个模块中的全部 117 个工具，以及 5 个跨模块工作流。完整实现请参见 tests/。

---

端到端测试套件

项目包含全面的测试套件，涵盖全部 117 个工具。

# Run all tests (requires server running)
node tests/run-all.cjs

# Run a single module
node tests/run-all.cjs --bucket mail --buckets-only

# Run only workflows
node tests/run-all.cjs --workflows-only

测试结构：

tests/
  lib/           Shared auth, HTTP client, reporter
  buckets/       One file per module (12 files, 117 tools)
  workflows/     Cross-module tests (5 files)
  run-all.cjs    Master runner

测试通过 ROPC 进行身份验证（无需手动管理令牌），运行时间约为 100 秒。

---

环境变量

将 .env.example 复制为 .env 并进行配置：

变量	必需	描述
MICROSOFT_CLIENT_ID	是	Azure 应用客户端 ID
MICROSOFT_TENANT_ID	是	Azure 租户 ID
MICROSOFT_REDIRECT_URI	否	OAuth 回调 URL（默认值：http://localhost:3000/api/auth/callback）
DEVICE_REGISTRY_ENCRYPTION_KEY	生产环境	用于令牌存储的 32 字节加密密钥
JWT_SECRET	生产环境	用于签署 JWT 令牌的密钥
CORS_ALLOWED_ORIGINS	生产环境	以逗号分隔的允许来源
PORT	否	服务端口（默认值：3000）
NODE_ENV	否	development 或 production

---

部署

本地（推荐用于入门）

npm install
npm run dev:web

Azure App Service

请参阅 docs/azure-deployment.md，了解使用 GitHub Actions 进行 CI/CD 部署。

---

安全性

• 加密存储：所有 Microsoft 令牌静态存储时均使用 AES-256 加密
• 无客户端密钥：桌面身份验证使用公共客户端流程（PKCE）
• 令牌隔离：每位用户的令牌分别存储，并使用不同的加密密钥
• 速率限制：内置速率限制功能，可防止滥用
• CORS 保护：生产环境中使用来源允许列表
• 会话过期：会话在 24 小时后过期

生产环境检查清单

• 设置 NODE_ENV=production
• 设置 DEVICE_REGISTRY_ENCRYPTION_KEY（32 字节）
• 设置 JWT_SECRET（强随机字符串）
• 设置 CORS_ALLOWED_ORIGINS
• 使用带有有效证书的 HTTPS

---

项目结构

MCP-Microsoft-Office/
├── mcp-adapter.cjs          MCP protocol adapter (runs locally with Claude Desktop)
├── src/
│   ├── api/                 Express routes and controllers
│   ├── auth/                MSAL authentication (OAuth2, ROPC, token exchange)
│   ├── core/                Services (cache, storage, tools, error handling)
│   ├── graph/               Microsoft Graph API services
│   │   ├── graph-client.cjs   HTTP client with retry, binary support, sessions
│   │   ├── files-service.cjs  OneDrive file operations
│   │   ├── excel-service.cjs  Workbook API (sessions, ranges, tables, functions)
│   │   ├── word-service.cjs   Word create/read (docx + mammoth + word-extractor)
│   │   └── powerpoint-service.cjs  PPT create/read (pptxgenjs + jszip)
│   └── modules/             Feature modules (mail, calendar, excel, word, powerpoint, etc.)
├── public/                  Web UI for authentication
└── tests/                   E2E test suite (gitignored)

---

贡献

1. Fork 此仓库
2. 创建功能分支
3. 完成更改
4. 提交拉取请求

---

许可证

MIT 许可证——详见 LICENSE 文件。