Model Context Protocol (MCP) 服务器 + Github OAuth

这是一个支持远程 MCP 连接的 Model Context Protocol (MCP) 服务器，内置了 Github OAuth 功能。

你可以将其部署到自己的 Cloudflare 账户中，在创建自己的 Github OAuth 客户端应用后，你就拥有了一个功能完备的远程 MCP 服务器，可以在此基础上继续开发。用户可以通过登录其 GitHub 账户来连接到你的 MCP 服务器。

你可以将此项目作为参考示例，了解如何使用 workers-oauth-provider 库 将其他 OAuth 提供商与部署在 Cloudflare 上的 MCP 服务器集成。

该 MCP 服务器（由 Cloudflare Workers 提供支持）：

• 对你的 MCP 客户端充当 OAuth 服务器

• 对你的 真实 OAuth 服务器（在本例中为 GitHub）充当 OAuth 客户端

[!WARNING] 这是一个演示模板，旨在帮助你快速上手。虽然我们已经实现了一些安全控制措施，但在部署到生产环境之前，你必须实施所有预防性和纵深防御安全措施。请查阅我们的综合安全指南：保护 MCP 服务器

快速开始

直接克隆仓库并安装依赖：npm install。

或者，你可以使用下面的命令行在本地机器上创建远程 MCP 服务器：

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-github-oauth

用于生产环境

创建一个新的 GitHub OAuth 应用：

• 对于 Homepage URL，指定 https://mcp-github-oauth.<your-subdomain>.workers.dev

• 对于 Authorization callback URL，指定 https://mcp-github-oauth.<your-subdomain>.workers.dev/callback

• 记下你的 Client ID 并生成一个 Client secret。

• 通过 Wrangler 设置密钥

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

[!IMPORTANT] 当你创建第一个密钥时，Wrangler 会询问是否要创建一个新的 Worker。输入 "Y" 以创建新的 Worker 并保存密钥。

设置 KV 命名空间

• 创建 KV 命名空间： wrangler kv namespace create "OAUTH_KV"

• 使用 KV ID 更新 Wrangler 文件

部署与测试

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

使用 Inspector 测试远程服务器：

npx @modelcontextprotocol/inspector@latest

输入 https://mcp-github-oauth.<your-subdomain>.workers.dev/sse 并点击连接。完成身份验证流程后，你将看到工具正常工作：

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

访问控制

此 MCP 服务器使用 GitHub OAuth 进行身份验证。所有通过身份验证的 GitHub 用户都可以访问 "add" 和 "userInfoOctokit" 等基本工具。

"generateImage" 工具仅限于 ALLOWED_USERNAMES 配置中列出的特定 GitHub 用户使用：

// Add GitHub usernames for image generation access
const ALLOWED_USERNAMES = new Set(["yourusername", "teammate1"]);

从 Claude Desktop 访问远程 MCP 服务器

打开 Claude Desktop，导航到 Settings -> Developer -> Edit Config。这将打开控制 Claude 可以访问哪些 MCP 服务器的配置文件。

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

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

当工具（在 🔨 下）出现在界面中后，你可以让 Claude 使用它们。例如："你能使用数学工具计算 23 加 19 吗？"。Claude 应该会调用该工具并显示 MCP 服务器生成的结果。

用于本地开发

如果你想迭代和测试 MCP 服务器，可以在本地开发环境中进行。这需要你在 GitHub 上创建另一个 OAuth 应用：

• 对于 Homepage URL，指定 http://localhost:8788

• 对于 Authorization callback URL，指定 http://localhost:8788/callback

• 记下你的 Client ID 并生成一个 Client secret。

• 在项目根目录创建一个 .dev.vars 文件，内容如下：

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

开发与测试

在本地运行服务器，使其在 http://localhost:8788 可用 wrangler dev

要测试本地服务器，请在 Inspector 中输入 http://localhost:8788/sse 并点击连接。按照提示操作后，你将能够 "List Tools"。

使用 Claude 和其他 MCP 客户端

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

使用 Cursor 和其他 MCP 客户端

要将 Cursor 与你的 MCP 服务器连接，请选择 Type："Command"，并在 Command 字段中将 command 和 args 字段合并为一个（例如 npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse）。

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

你可以将 MCP 服务器连接到其他 MCP 客户端（如 Windsurf），方法是打开客户端的配置文件，添加与 Claude 设置相同的 JSON，然后重新启动 MCP 客户端。

它是如何工作的？

OAuth 提供商

OAuth Provider 库是面向 Cloudflare Workers 的完整 OAuth 2.1 服务器实现。它处理 OAuth 流程的复杂性，包括令牌签发、验证和管理。在本项目中，它扮演着双重角色：

• 对连接到服务器的 MCP 客户端进行身份验证

• 管理与 GitHub OAuth 服务的连接

• 在 KV 存储中安全地存储令牌和身份验证状态

Durable MCP

Durable MCP 将基础 MCP 功能与 Cloudflare 的 Durable Objects 扩展，提供：

• 为 MCP 服务器提供持久化状态管理

• 在请求之间安全存储身份验证上下文

• 通过 this.props 访问已认证用户信息

• 支持基于用户身份的条件性工具可用性

MCP Remote

MCP Remote 库使你的服务器能够公开可供 Inspector 等 MCP 客户端调用的工具。它：

• 定义客户端与服务器之间的通信协议

• 提供定义工具的结构化方式

• 处理请求和响应的序列化与反序列化

• 维护客户端与服务器之间的 Server-Sent Events (SSE) 连接