VINdata MCP

Model Context Protocol（MCP）服务 + Github OAuth

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

你可以将它部署到自己的 Cloudflare 账户，并在创建自己的 Github OAuth 客户端应用后，获得一个可供扩展的完整远程 MCP 服务。用户可以使用自己的 GitHub 账户登录并连接到你的 MCP 服务。

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

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

• 作为 MCP 客户端的 OAuth 服务端
• 作为你的_实际_ OAuth 服务端（本例中为 GitHub）的 OAuth 客户端

警告

这是一个演示模板，旨在帮助你快速入门。虽然我们已实施多项安全控制措施，但在部署到生产环境之前，你必须实施所有预防性和纵深防御安全措施。请查看我们的完整安全指南：保护 MCP 服务

开始使用

直接克隆仓库并安装依赖项：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

重要

创建第一个密钥时，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 并点击连接。按照提示操作后，即可“列出工具”。

使用 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 提供方

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