JBAssist - Microsoft Graph MCP Server

JBAssist - Microsoft Graph MCP 服务

一个兼容 Windows 的模型上下文协议（MCP）服务实现，可将 Claude Desktop 连接到 Microsoft Graph API。

概述

本项目提供了一个简单的 MCP 服务，允许 Claude 通过 Microsoft Graph API 与 Microsoft 365 服务交互。该服务提供多种工具，可访问标准和 Beta 版 Graph API 功能。

标准 API 工具

1. get-profile：获取当前用户的个人资料信息
2. get-emails：检索用户收件箱中的近期邮件
3. get-calendar-events：获取指定天数内即将举行的日历事件
4. search-users：搜索组织中的用户

Beta API 工具（扩展用户功能）

1. get-enhanced-profile：获取详细的用户个人资料信息，包括技能、兴趣、学校等
2. get-direct-reports：获取用户的直接下属及其详细信息
3. get-manager：获取用户的经理信息
4. get-presence：获取用户的状态信息（可用性状态）
5. get-teamwork：获取用户的 Microsoft Teams 和团队协作活动
6. advanced-user-search：按技能、部门、职位等高级条件筛选并搜索用户

前提条件

• Node.js 18 或更高版本
• 支持 MCP 的 Claude Desktop
• Windows 10 或 11
• 具有适当权限的 Microsoft 365 账户
• 具有适当权限的 Azure AD 应用注册

设置

1. 创建 Azure AD 应用注册

1. 前往 Azure Portal 并导航到 Azure Active Directory
2. 选择“App registrations”，然后点击“New registration”
3. 为应用输入名称（例如“JBAssist”）
4. 在“Supported account types”中选择“Accounts in this organizational directory only”
5. 点击“Register”
6. 记下“Application (client) ID”和“Directory (tenant) ID”的值
7. 在“Certificates & secrets”下创建新的客户端密钥，并记下其值

2. 配置 API 权限

1. 在应用注册中，前往“API permissions”
2. 点击“Add a permission”，然后选择“Microsoft Graph”
3. 选择“Application permissions”（用于守护进程／服务访问）或“Delegated permissions”（用于用户访问）
4. 添加以下权限：
   • User.Read
   • Mail.Read
   • Calendars.Read
   • User.Read.All（用于搜索用户）
   • Presence.Read.All（用于状态信息）
   • TeamMember.Read.All（用于 Teams 信息）
5. 点击“Add permissions”
6. 点击“Grant admin consent for [your organization]”

3. 克隆并配置代码库

1. 克隆此代码库：

   git clone https://github.com/JBAgent/JBAssist.git
   cd JBAssist
   

2. 根据 .env.example 模板创建 .env 文件：

   cp .env.example .env
   

3. 使用 Azure AD 应用详情编辑 .env 文件：

   TENANT_ID=your-tenant-id
   CLIENT_ID=your-client-id
   CLIENT_SECRET=your-client-secret
   SCOPES=User.Read,Mail.Read,Calendars.Read,User.Read.All,Presence.Read.All,TeamMember.Read.All
   

4. 安装依赖项：

   npm install
   

5. 构建项目：

   npm run build
   

在 Claude Desktop 中运行 Microsoft Graph 服务

1. 首先，启动 Claude Desktop

2. 使用以下任一方法运行服务：

   • PowerShell：

     .\run-graph-server.ps1
     

   • Command Prompt：

     run-graph-server.bat
     

   • 或直接使用 Node.js：

     npm start
     

3. 在 Claude Desktop 中，点击右上角的拼图图标（🧩），打开 MCP 服务选择器

4. 选择“Add MCP Server”，并在提示输入服务名称时输入 msgraph

5. 你应该会看到 Microsoft Graph 服务已成功连接的确认信息

使用 Microsoft Graph 工具

连接后，你可以用自然语言让 Claude 使用 MS Graph 工具，例如：

标准 API 示例

• “你能给我看看我的个人资料信息吗？”
• “我最近收到了哪些邮件？”
• “显示我未来一周的日历事件。”
• “你能搜索名为 John 的用户吗？”

Beta API 示例

• “获取包含技能和兴趣的增强版个人资料。”
• “我的直接下属有哪些人？”
• “我的经理是谁？”
• “我当前的状态是什么？”
• “向我显示我的 Teams 信息。”
• “搜索市场部中具备 SQL 技能的用户。”

Beta API 功能

Microsoft Graph beta API 提供对仍在开发中的功能的访问权限。这些功能可能会发生变化，也可能不稳定。beta API 可提供以下访问权限：

增强版用户个人资料

beta API 提供更多用户个人资料信息，包括：

• 技能和专业知识
• 兴趣
• 过往项目
• 教育经历
• 职责
• 关于我的信息
• 生日
• 首选语言
• 备用电子邮件地址

组织关系

• 直接下属层级
• 经理信息
• 团队成员身份
• 团队状态和状态信息

状态信息

• 用户可用状态
• 活动信息
• 状态消息
• Teams 状态信息

高级搜索

• 按技能搜索
• 按部门搜索
• 按职位名称搜索
• 使用多个筛选条件进行组合搜索

故障排除

如果遇到问题：

1. 身份验证错误：仔细检查 .env 文件中的 Azure AD 应用凭据

2. 权限错误：确保已为 Azure AD 应用授予适当的权限

3. 连接错误：当 Claude Desktop 提示授予 MCP 权限时，确保已点击“允许”按钮

4. 日志文件：检查 graph-server.log 文件以获取详细的错误信息

5. 路径问题：确保 Node.js 和 npm 已添加到系统的 PATH 变量中

6. Windows 中的权限错误：尝试以管理员身份运行命令提示符或 PowerShell

7. Beta API 错误：请记住，beta API 终结点可能会发生变化，或与文档描述的行为不同

开发

若要修改服务或添加新功能：

1. 编辑 src 目录中的文件
2. 按照现有模式在 src/index.ts 中添加新工具
3. 使用 npm run build 重新构建
4. 重启服务

添加新的 Beta API 功能

添加新的 beta API 功能时：

1. 参考 Microsoft Graph beta API 文档
2. 使用 graphBetaClient 实例调用 beta API
3. 进行全面测试，因为 beta API 可能会发生变化
4. 为 beta 功能添加适当的错误处理
5. 记录任何限制或已知问题

其他 Microsoft Graph 终结点

此服务提供基本功能，但 Microsoft Graph 还提供许多其他终结点。以下是一些可以添加的示例：

• OneNote 访问
• SharePoint 文档访问
• Teams 消息访问
• OneDrive 文件访问
• 任务管理

请参阅 Microsoft Graph 文档了解更多终结点。

许可证

MIT

致谢

此项目基于 Windows MCP Weather 示例，并经过改编以适配 Microsoft Graph。