Office MCP服务器
这是Office MCP（模型上下文协议）服务器的全面实现，通过Microsoft Graph API将Claude与Microsoft 365服务连接起来。
无头操作！ 初始设置后，无需浏览器身份验证即可运行。自动令牌刷新和Windows任务计划程序支持不可见的后台操作。看 任务_时间表_SETUP.md Windows安装指南。
开发状态：该项目正在积极开发中，尚未投入生产。API、接口和功能可能会更改，恕不另行通知。请自行承担风险，仅用于评估和测试目的。不建议用于生产部署。
特性
- 完成Microsoft 365集成：电子邮件、日历、团队、OneDrive/SharePoint、联系人、计划器、待办事项、组和目录
- 整合工具架构：基于操作的路由减少了工具数量，实现了LLM上下文的高效使用
- 无头操作：初始身份验证后不使用浏览器运行
- 自动令牌管理：具有自动刷新功能的持久令牌存储
- 共享邮箱支持：访问共享邮箱
.Shared范围 - 集中错误处理：具有针对Graph API错误的可操作提示的一致错误格式
- 电子邮件附件处理：下载嵌入式附件并将SharePoint URL映射到本地路径
- 高级电子邮件搜索：支持KQL和自动查询优化的统一搜索
- 团队会议管理：访问成绩单、录音和人工智能见解
- 文件管理：支持跨驱动器的完整OneDrive和SharePoint文件操作
- 联系人管理：使用高级搜索对Outlook联系人进行完整的CRUD操作
- 任务管理：Microsoft Planner和待办事项集成
- 可配置路径：所有本地同步路径的环境变量
快速开始
先决条件
- Node.js 16或更高版本
- Microsoft 365帐户（个人或工作/学校）
- Azure应用程序注册（见下文）
安装
- 克隆存储库：
git clone https://github.com/yourusername/office-mcp.git
cd office-mcp- 安装依赖项：
npm install- 复制环境模板：
cp .env.example .env- 配置您的
.env文件包含：
- Azure应用程序凭据（请参阅下面的Azure设置） - SharePoint/OneDrive同步的本地文件路径 - 可选设置
- 运行初始身份验证：
npm run auth-server
# Visit http://localhost:3000/auth and sign in- 配置Claude桌面（请参阅下面的Claude桌面配置）
工具架构
服务器使用整合的工具设计，其中每个Microsoft 365域都作为单个工具公开 operation （以及可选 entity)路由。这最大限度地减少了LLM上下文开销，同时提供了完整的功能。
| 工具 | 域 | 操作 |
|---|---|---|
system | 身份验证和服务器信息 | about, authenticate, check_status |
mail | 电子邮件 | list, read, send, reply, draft, search, move, folder, rules, categories, focused |
calendar | 日历事件 | list, get, create, update, delete, find_free_slots |
teams_meeting | 团队会议 | create, update, cancel, find, list_transcripts, get_transcript, get_recordings |
teams_channel | 团队频道 | list, create, get, update, delete, send_message, list_messages, list_members |
teams_chat | 团队聊天 | list, create, get, send_message, list_messages, list_members |
files | OneDrive/SharePoint | list, get, search, upload, download, create_folder, delete, move, copy, share --所有操作都支持交叉驱动 driveId |
search | 统一搜索 | 跨邮件、文件、事件的基于关键字的搜索--返回 ID 和 DriveID 取得可操作的结果 |
contacts | Outlook联系人 | list, get, create, update, delete, search, list_folders |
planner | Microsoft Planner | 实体+操作： plan.list, task.create, bucket.get_tasks, user.lookup等等。 |
todo | 微软要做 | list_lists, create_list, list_tasks, create_task, update_task, list_checklist等等。 |
groups | M365组 | list, get, create, update, delete, list_members, add_member, remove_member, list_owners, get_drive, list_drives |
directory | 用户目录 | lookup_user, get_profile, get_manager, get_reports, get_presence, search_users |
notifications | Webhooks | create, list, renew, delete |
错误处理
所有工具都用 safeTool() 其提供：
- 一致的
isError: true故障响应 - 上下文标记的消息（例如。，
[calendar.create] Error: ...) - 常见Graph API错误的可操作提示（401403404429）
Azure应用程序注册和配置
要使用此MCP服务器，您需要首先在Azure门户中注册和配置应用程序。以下步骤将引导您完成注册新应用程序、配置其权限和生成客户端密钥的过程。
应用注册
- 打开 Azure 门户 在浏览器中
- 使用Microsoft工作或个人帐户登录
- 搜索或点击“应用程序注册”
- 点击“新注册”
- 输入应用程序的名称，例如“Office MCP Server”
- 选择“任何组织目录中的帐户和个人Microsoft帐户”选项
- 在“重定向URI”部分，从下拉列表中选择“Web”并输入http://localhost:3000/auth/callback“在文本框中
- 点击“注册”
- 从应用程序设置页面的概述部分，复制“应用程序（客户端）ID”，并将其作为OFFICE_client_ID输入.env文件和claude-config-sample.json文件
应用程序权限
- 从Azure门户的应用程序设置页面中，选择“管理”部分下的“API权限”选项
- 点击“添加权限”
- 点击“Microsoft Graph”
- 选择“委派权限”
- 搜索并选中这些权限旁边的复选框：
- 离线访问 - 用户。阅读 - 用户。读写 - 用户。阅读基础。全部 - 邮件。读写 - 邮件。发送 - 邮件。读写。共享 - 邮件。发送。共享 - 邮箱设置。读写 - 日历。读写 - 联络。读写 - 文件夹。读写。全部 - 团队。阅读基础。全部 - 团队。创建 - 聊天。读写 - 频道消息。读。全部 - 频道消息。发送 - 在线会议记录。读。全部 - 在线会议。读写 - 任务。读写 - 集团。读。全部 - 目录。读。全部 - 在场。读写 - 地点。读。全部
- 点击“添加权限”
客户端密钥
- 在Azure门户的应用程序设置页面中，选择管理部分下的“证书和机密”选项
- 切换到“客户端机密”选项卡
- 点击“新客户机密”
- 输入描述，例如“客户端密码”
- 选择最长可能的过期时间
- 点击“添加”
- 复制secret值，并将其作为OFFICE_CLIENT_secret输入.env文件和claude-config-sample.json文件中
环境配置
必需变量
# Azure App Registration
OFFICE_CLIENT_ID=your-azure-app-client-id
OFFICE_CLIENT_SECRET=your-azure-app-client-secret
OFFICE_TENANT_ID=common
# Authentication
OFFICE_REDIRECT_URI=http://localhost:3000/auth/callback可选变量
# Local file paths (customize to your system)
SHAREPOINT_SYNC_PATH=/path/to/your/sharepoint/sync
ONEDRIVE_SYNC_PATH=/path/to/your/onedrive/sync
TEMP_ATTACHMENTS_PATH=/path/to/temp/attachments
SHAREPOINT_SYMLINK_PATH=/path/to/sharepoint/symlink
# Server settings
USE_TEST_MODE=false
TRANSPORT_TYPE=stdio # or 'http' for SSE headless mode
HTTP_PORT=3333
HTTP_HOST=127.0.0.1Claude桌面配置
- 找到您的Claude Desktop配置文件：
- 窗户： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json
- 添加MCP服务器配置：
{
"mcpServers": {
"office-mcp": {
"command": "node",
"args": ["/path/to/office-mcp/index.js"],
"env": {
"OFFICE_CLIENT_ID": "your-client-id",
"OFFICE_CLIENT_SECRET": "your-client-secret",
"SHAREPOINT_SYNC_PATH": "/path/to/sharepoint",
"ONEDRIVE_SYNC_PATH": "/path/to/onedrive"
}
}
}
}- 重新启动克劳德桌面
- 在克劳德，使用
system工具与operation: "authenticate"连接到Microsoft 365
测试
MCP检查员
使用MCP检查器直接测试服务器：
npx @modelcontextprotocol/inspector node index.js测试模式
启用测试模式以在没有API调用的情况下使用模拟数据：
USE_TEST_MODE=true node index.js单元测试
npm test身份验证流程
- 启动身份验证服务器：
- 跑 ./start-auth-server.sh （或使用 npm run auth-server)
- 身份验证服务器在端口3000上运行，并处理OAuth回调
- 在克劳德，使用
system工具与operation: "authenticate"获取身份验证URL - 在浏览器中完成身份验证
- 代币存储在
~/.office-mcp-tokens.json
无头操作
自动令牌刷新
初始身份验证后，服务器会自动刷新令牌，无需用户交互。
HTTP/SSE传输模式
对于无头环境，使用SSE传输：
TRANSPORT_TYPE=http HTTP_PORT=3333 node index.js服务器暴露 /sse （GET）用于SSE连接和 /message （POST）用于客户端消息。
Windows服务（可选）
对于Windows后台操作：
- 完成初始身份验证
- 配置为Windows任务计划程序任务
- 在系统启动时不可见地运行
故障排除
常见问题
- 身份验证错误
- 确保Azure应用程序具有正确的权限 - 检查令牌文件是否存在： ~/.office-mcp-tokens.json - 验证重定向URI是否与Azure配置匹配
- 使用日期过滤器进行电子邮件搜索
- 经过日期过滤的搜索现在直接路由到$filter API以提高可靠性 - 使用通配符 * 适用于日期范围内的所有电子邮件 - 两者 startDate 和 endDate 支持ISO格式（2025-08-27）或相关格式（7d/1w/1m/1y）
- 电子邮件附件问题
- 在中配置本地同步路径 .env - 确保临时目录具有写入权限 - 检查SharePoint同步是否处于活动状态
- API费率限制
- 服务器包括指数回退的自动重试 - 如果持续存在，请降低请求频率
- 权限错误
- 验证是否已授予所有必需的Graph API权限 - 某些权限可能需要管理员同意
安全注意事项
- 安全令牌存储：使用原子写入以限制文件权限（0o600）存储令牌，以防止损坏
- 无凭据记录：令牌内容从不记录；仅使用布尔型存在检查
- 敏感数据补救：不记录电子邮件正文、收件人和搜索查询；带有查询参数的API URL在DEBUG_VERBOSE之后被选通
- 环境变量：从不承诺
.env文件 - 客户秘密：定期轮换并在生产中使用Azure密钥库
- 本地路径：使用环境变量而不是硬编码路径
- 优雅地关闭：正确处理SIGTERM/SIGINT以终止清洁流程
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件