Model Context Protocol (MCP) Server + Github OAuth

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

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

你可以将它部署到自己的 Cloudflare 账户。创建自己的 Github OAuth 客户端应用后，你就会拥有一个可供扩展的完整远程 MCP 服务。用户可以通过使用自己的 GitHub 账户登录来连接到你的 MCP 服务。

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

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

• 充当 MCP 客户端的 OAuth 服务端
• 充当 真正的 OAuth 服务端（此处为 GitHub）的 OAuth 客户端

开始使用

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

用于生产环境

创建一个新的 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，然后点击连接。完成身份验证流程后，你就会看到工具正常运行：

现在，你已经部署好远程 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，然后点击连接。按照提示操作后，你就可以“列出工具”。

使用 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）连接