使用说明

模型上下文协议（MCP）服务器 + Microsoft Entra ID OAuth + 任务管理

这是一个模型上下文协议（MCP）支持远程MCP连接的服务器，内置Microsoft Entra ID（原Azure AD）OAuth功能，并且 全面的Microsoft To Do任务管理功能。

您可以将其部署到您自己的Cloudflare账户中，创建自己的Azure AD OAuth应用程序后，您将拥有一个功能齐全的远程MCP服务器，可以在此基础上进行构建。用户将能够通过登录他们的Microsoft账户连接到您的MCP服务器，管理他们的待办事项列表、创建任务、设置提醒等。

你可以将此作为参考示例，了解如何使用（此处原文似乎不完整，假设后续有具体工具或方法）将其他OAuth提供商与部署在Cloudflare上的MCP服务器进行集成 workers-oauth-provider 图书馆。

MCP服务器（由...提供支持） Cloudflare Workers（云网工作者）):

作为OAuth（开放授权协议） 服务器 致您的MCP客户
作为OAuth（的一种）客户致你的 真实的 OAuth服务器（在此情况下为Microsoft Entra ID）

入门指南/开始使用

克隆仓库并安装依赖项： npm install

用于生产

创建一个新的Azure AD应用程序：

首选 Azure 门户 → Azure Active Directory → 应用注册
点击 新注册
配置：
- 名字： MCP Entra OAuth Todo Server
- 支持的账户类型：
  - 为了 多租户 支持（推荐）：选择 “任何组织目录（任何Azure AD目录 - 多租户）中的账户以及个人Microsoft账户”
  - 仅限单个组织：选择 “仅限此组织目录中的帐户”
- 重定向URI:
  - 类型： Web
  - URI（统一资源标识符）: https://remote-mcp-entra-oauth-todo.<your-subdomain>.workers.dev/callback
  - 同时补充： http://localhost:8789/callback （发展）
注册后，请记下：
- 应用程序（客户端）ID
- 目录（租户）ID
创建客户端密钥：
- 首选 证书与密钥 → 新的客户端密钥
- 立即复制密钥值（之后将无法再次查看）
配置API权限：
- 首选 API权限 → 添加一个权限 → Microsoft Graph（微软图） → 委托权限
- 添加：
  - User.Read （登录并阅读用户资料）
  - Tasks.ReadWrite （读取和写入用户任务）
- 点击 授予管理员同意 为您的组织
💡 专业小贴士这段代码使用了 https://graph.microsoft.com/.default 范围，它会动态地请求所有预先同意的权限。若要添加新的工具或权限，只需在Azure门户中添加并授予同意即可——无需更改代码！
通过Wrangler设置密钥：

wrangler secret put ENTRA_CLIENT_ID
wrangler secret put ENTRA_CLIENT_SECRET
wrangler secret put ENTRA_TENANT_ID  # Use 'common' for multi-tenant, or your specific tenant ID
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32
wrangler secret put DEFAULT_TIMEZONE # optional, defaults to Europe/London

[!重要] 多租户配置在设置时 ENTRA_TENANT_ID：

使用 common - 支持工作/学校账户和个人微软账户（建议用于多租户环境）

使用 organizations - 仅允许工作/学校账户（Azure AD），不允许个人账户

使用 consumers - 仅允许使用个人微软账户

使用您的特定租户ID - 仅限该特定租户的用户

对于多租户应用，使用 common 确保在用户所属的主租户上下文中颁发令牌，从而允许他们即使在其他租户中作为访客用户也能访问其个人资源（如待办事项列表）。

[!重要] 当你创建第一个秘密时，Wrangler 会询问你是否想要创建一个新的 Worker。输入“Y”来创建一个新的 Worker 并保存该秘密。

时区配置：

设置 DEFAULT_TIMEZONE 到您偏好的时区（例如。， Asia/Tokyo， America/New_York， Europe/London)
除非另有指定，否则此时区将用于所有任务的截止日期和提醒
用户仍然可以在需要时为每个任务指定不同的时区
如果未设置，则默认为 Europe/London

设置一个KV命名空间

创建KV命名空间： wrangler kv namespace create "OAUTH_KV"
使用KV ID更新Wrangler文件

部署与测试

部署MCP服务器，使其在workers.dev域名下可用 wrangler deploy

使用（工具/方法）测试远程服务器检查员：

npx @modelcontextprotocol/inspector@latest

输入 https://remote-mcp-entra-oauth-todo.<your-subdomain>.workers.dev/mcp 然后点击连接。一旦您完成身份验证流程，您就会看到工具开始工作。

您现在已经部署了一个远程MCP服务器！

从Claude桌面访问远程MCP服务器

打开Claude桌面版，然后导航至“设置”->“开发者”->“编辑配置”。这将打开控制Claude可以访问的MCP服务器的配置文件。

将内容替换为以下配置。重启Claude Desktop后，将打开一个浏览器窗口，显示您的OAuth登录页面。完成认证流程以授予Claude访问您的MCP服务器的权限。授权后，工具即可供您使用。

{
  "mcpServers": {
    "entra-todo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote-mcp-entra-oauth-todo.<your-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

一旦工具（位于🔨下方）出现在界面上，您就可以请求Claude使用它们。例如：

“你能从 Microsoft Graph 中获取我的用户配置文件吗？”
“显示我的所有待办事项列表”
“在我的工作列表中创建一个新任务，截止日期为下周五”
“我这周有哪些任务要完成？”

用于本地开发

如果您想在本地开发环境中迭代并测试您的MCP服务器，您可以这样做。这将需要您在Azure AD中创建另一个OAuth应用程序：

对于主页URL，请指定 http://localhost:8789
对于授权回调URL，请指定 http://localhost:8789/callback
记下您的客户端ID并生成一个客户端密钥。
创建一个 .dev.vars 在项目根目录中创建文件，内容为：

ENTRA_CLIENT_ID=your_development_azure_ad_client_id
ENTRA_CLIENT_SECRET=your_development_azure_ad_client_secret
ENTRA_TENANT_ID=common  # Use 'common' for multi-tenant, or your specific tenant ID
COOKIE_ENCRYPTION_KEY=any_random_string_here
DEFAULT_TIMEZONE=Europe/London

开发与测试

在本地运行服务器，以便通过 http://localhost:8789 wrangler dev

要测试本地服务器，请输入 http://localhost:8789/mcp 进入“检查器”并点击连接。按照提示操作后，您将能够“列出工具”。

使用Claude及其他MCP客户端

当你使用Claude连接到你的远程MCP服务器时，可能会看到一些错误信息。这是因为Claude Desktop目前还不支持远程MCP服务器，所以有时会感到困惑。要验证MCP服务器是否已连接，请将鼠标悬停在Claude界面右下角的🔨图标上。你应该会看到你的工具在那里显示。

使用 Cursor 和其他 MCP 客户端

要将Cursor连接到您的MCP服务器，请选择 Type“命令”和在 Command 字段，将命令和参数字段合并为一个（例如。 npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/mcp）。

请注意，虽然 Cursor 支持 HTTP+SSE 服务器，但它不支持身份验证，因此您仍然需要使用 mcp-remote （并且要使用STDIO服务器，而不是HTTP服务器）。

你可以通过打开客户端的配置文件，添加用于Claude设置的相同JSON配置，然后重启MCP客户端，将你的MCP服务器连接到其他MCP客户端，如Windsurf。

它是如何工作的？

OAuth 提供者

OAuth 提供者库为 Cloudflare Workers 提供了一个完整的 OAuth 2.1 服务器实现。它处理了 OAuth 流程的复杂性，包括令牌的颁发、验证和管理。在这个项目中，它扮演着双重角色：

验证连接到您服务器的MCP客户端
管理与Microsoft Entra ID的OAuth服务的连接
在键值存储中安全地存储令牌和认证状态

持久性多路径控制协议（或根据具体上下文，可译为“耐用型多路径控制协议”）

持久化MCP通过Cloudflare的持久化对象（Durable Objects）扩展了基础MCP的功能，提供：

为您的MCP服务器提供持久化状态管理
在请求之间安全地存储认证上下文
通过（某种方式）访问经过验证的用户信息 this.props
根据用户身份支持条件性工具可用性

MCP 远程

MCP Remote库使您的服务器能够暴露工具，这些工具可以被MCP客户端（如Inspector）调用。它

定义客户端与您的服务器之间的通信协议
提供了一种结构化的方式来定义工具
处理请求和响应的序列化与反序列化
支持客户端通信的Streamable HTTP（推荐）和Server-Sent Events（SSE）协议

传输协议迁移

此示例已更新以支持新功能 可流式传输的HTTP 传输协议，该协议取代了已弃用的服务器发送事件（SSE）协议。服务器现在公开了两个端点：

/mcp - 推荐使用新的Streamable HTTP协议
/sse - 已弃用遗留的SSE协议（为保持向后兼容而维护）

所有新的集成都应该使用 /mcp 端点。SSE 端点将在未来的版本中移除。

可用工具

用户配置文件

getUserProfile - 获取已认证用户的Microsoft Graph个人资料

待办事项管理

listTodoLists - 获取已认证用户的全部待办事项列表
createTodoList - 创建一个指定名称的新任务列表
updateTodoList - 更新现有任务列表的名称
deleteTodoList - 删除任务列表

任务管理

listTasks - 从特定的待办事项列表中获取所有任务
getTask - 获取特定任务的详细信息
createTask - 创建一个带有可选属性的新任务：
- 标题（必填）
- 身体/描述
- 截止日期和时间
- 提醒日期和时间
- 重要性级别（低、正常、高）
- 类别/标签
- 日期的时间时区
updateTask - 更新任何任务属性：
- 标题
- 身体/描述
- 状态（未开始、进行中、已完成、等待他人、已延期）
- 重要性水平
- 截止日期和时间
- 提醒设置
- 类别
deleteTask - 从列表中删除任务

简单测试工具

add - 加两个数（用于测试MCP连接）

使用示例

请Claude帮助你完成以下任务：

“显示我的所有待办事项列表”
“创建一个名为‘购物’的新列表”
“在我的购物清单中添加一项任务‘购买杂货’，截止日期为明天下午5点”
“我的工作列表里有哪些任务？”
“将任务‘致电客户’更新为高优先级，截止日期为周五”
“将‘提交报告’任务标记为已完成”
“为我明天上午9点的‘团队会议准备’任务设置提醒”
“从我的个人列表中删除所有已完成的任务”

添加新工具

多亏了 .default 在OAuth流程中使用的范围，添加新工具非常直接：

在Azure门户中添加权限：
- 前往您的应用 → API 权限
- 这个 Tasks.ReadWrite 已完成对待办事项功能的权限设置
- 如果尚未完成，请授予管理员同意
在代码中添加工具 (src/index.ts):

this.server.tool(
  "getTodoTaskList",
  "Get details of a specific todo task list",
  {
    listId: z.string().describe("The ID of the todo list to retrieve"),
  },
  async ({ listId }) => {
    const client = Client.init({
      authProvider: (done) => {
        done(null, this.props!.accessToken);
      },
    });

    try {
      const taskList = await client
        .api(`/me/todo/lists/${listId}`)
        .get();

      return {
        content: [{ text: JSON.stringify(taskList, null, 2), type: "text" }],
      };
    } catch (error) {
      return {
        content: [{
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
          type: "text"
        }],
        isError: true,
      };
    }
  }
);

部署: npm run deploy

就这样！OAuth 流程中无需进行范围（scope）更改，因为 .default 动态请求所有预先同意的权限。

安全注意事项

✅ 客户端密钥以Cloudflare Workers密钥的形式存储（永远不会暴露给客户端）
✅ OAuth 状态参数防止 CSRF 攻击
✅ 使用HMAC签名的cookie以保持审批对话框的持久性
✅ 访问令牌在MCP会话令牌中被加密
✅ 所有通信均通过HTTPS进行
✅ 授权前，审批对话框显示客户端信息

故障排除

“无法获取访问令牌”

在Azure门户中检查客户端密钥是否正确且未过期
验证重定向URI完全匹配（包括协议和端口）
确保 ENTRA_TENANT_ID 正确无误

“Tasks.ReadWrite 权限被拒绝”

确保在 Azure 门户中已获得管理员同意
检查用户在Azure AD中是否具有适当的权限
验证权限是否已添加为 （被）委托的 权限，而非应用程序权限

“无效的租户”

验证您的密钥中 ENTRA_TENANT_ID 是否正确
对于多租户应用程序，请使用 common 作为租户ID，支持工作/学校账户和个人账户
使用 organizations 仅限工作/学校账户使用，或 consumers 仅限个人账户使用
如果使用特定租户，请确保租户ID与Azure门户中显示的租户ID一致
对访客用户而言很重要如果用户是您租户中的访客，但试图访问他们的个人资源（如待办事项），您必须使用 common 因此，令牌是在其主租户上下文中颁发的

Claude Desktop 的连接问题

更新配置后重启Claude桌面版
检查Worker URL是否正确且可访问
验证所有密钥是否已正确设置，使用 wrangler secret list

任务中的时区问题

验证你的密钥中 DEFAULT_TIMEZONE 是否设置正确
使用标准时区名称（例如。， America/New_York，不是 EST)
您可以在工具参数中指定每个任务的时区，以覆盖默认时区设置

建筑学

此实现遵循标准的OAuth 2.0授权码流程：

用户打开MCP客户端 客户端尝试连接到您的MCP服务器
服务器发起OAuth → 显示包含客户信息的确认对话框
用户已批准 → 重定向到 Microsoft 登录页面
用户身份验证 → Microsoft 重定向回传授权码
服务器交换代码 → 使用客户端密钥从微软获取访问令牌
服务器获取用户信息 → 调用 Microsoft Graph 获取用户配置文件
发行的代币 → MCP客户端接收带有用户上下文的加密令牌
可用的工具 现在，客户端可以使用委托权限调用 Microsoft Graph 工具

Cloudflare Worker 作为 保密客户 （服务器端应用程序）该程序：

安全地存储客户端密钥
处理完整的OAuth流程
将授权码兑换为访问令牌
代表经过身份验证的用户调用 Microsoft Graph API

许可证

麻省理工学院（MIT）