Model Context Protocol (MCP) Server + Github OAuth

Model Context Protocol (MCP) 服务 + Github OAuth

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

你可以将其部署到自己的 Cloudflare 账户。创建自己的 Github OAuth 客户端应用后，就会获得一个功能完备的远程 MCP 服务，可在此基础上进行构建。用户可以通过使用自己的 GitHub 账户登录，连接到你的 MCP 服务。

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

这个由 Cloudflare Workers 提供支持的 MCP 服务：

• 作为 MCP 客户端的 OAuth 服务端
• 作为 真实 OAuth 服务端（此处为 GitHub）的 OAuth 客户端

入门

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

也可以使用下面的命令行，在本地计算机上创建远程 MCP 服务：

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

用于生产环境

创建一个新的 GitHub OAuth App：

• 对于 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

设置 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 并点击 connect。完成身份验证流程后，你会看到工具已正常运行：

现在，你已经部署好了远程 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 使用它们。例如：“你能用 math 工具计算 23 和 19 的和吗？”Claude 应会调用该工具，并显示 MCP 服务生成的结果。

用于本地开发

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

• 对于 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 并点击 connect。按照提示操作后，你就可以“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 服务连接到 Windsurf 等其他 MCP 客户端：打开客户端的配置文件，添加与 Claude 设置相同的 JSON，然后重启 MCP 客户端。

它是如何工作的？

OAuth Provider

OAuth Provider 库是一个适用于 Cloudflare Workers 的完整 OAuth 2.1 服务端实现。它负责处理 OAuth 流程中的复杂环节，包括令牌签发、验证和管理。在本项目中，它承担双重职责：

• 对连接到您服务的 MCP 客户端进行身份验证
• 管理与 GitHub OAuth 服务的连接
• 在 KV 存储中安全保存令牌和身份验证状态

Durable MCP

Durable MCP 利用 Cloudflare Durable Objects 扩展了基础 MCP 功能，提供：

• 为您的 MCP 服务进行持久化状态管理
• 在请求之间安全存储身份验证上下文
• 通过 this.props 访问经过身份验证的用户信息
• 根据用户身份有条件地提供工具

MCP Remote

MCP Remote 库使您的服务能够向 Inspector 等 MCP 客户端提供可调用的工具。它：

• 定义客户端与您的服务之间的通信协议
• 提供结构化的工具定义方式
• 处理请求和响应的序列化与反序列化
• 维护客户端与您的服务之间的服务器发送事件（SSE）连接