远程MCP服务器带认证

Name: 远程MCP服务器带认证
Author: coleam00

作者：coleam00270 星标更新：2025-07-12

安装使用来源：spider==github.com

项目介绍

Cloudflare 远程 PostgreSQL 数据库 MCP 服务器 + GitHub OAuth

这是一个模型上下文协议（MCP）服务器，它允许您与您的 PostgreSQL 数据库进行聊天，并通过 Cloudflare 部署为带有 GitHub OAuth 的远程 MCP 服务器。这是一个生产就绪的 MCP。

主要功能

🗄️ 生命周期数据库集成：所有 MCP 工具调用的直接 PostgreSQL 数据库连接
🛠️ 模块化单一用途工具：遵循 MCP 工具及其描述的最佳实践
🔐 基于角色的访问：基于 GitHub 用户名的数据库写操作权限
📊 架构发现：自动检索表和列信息
🛡️ SQL 注入保护：内置验证和清理
📈 监控：可选的 Sentry 集成用于生产监控
☁️ 云原生：由 Cloudflare Workers 提供支持，实现全球规模

模块化架构

此 MCP 服务器使用干净、模块化的架构，使其易于扩展和维护：

src/tools/ - 单独文件中的各个工具实现
registerAllTools() - 中央工具注册系统
可扩展设计 - 通过在 tools/ 中创建文件并注册它们来添加新工具

这种架构允许您轻松地添加新的数据库操作、外部 API 集成或任何其他 MCP 工具，同时保持代码库的组织性和可维护性。

传输协议

此 MCP 服务器支持现代和遗留传输协议：

/mcp - 可流式传输的 HTTP（推荐）：使用单个端点进行双向通信，自动连接升级，以及更好的网络中断恢复能力
/sse - 服务器发送事件（遗留）：使用单独的请求/响应端点，为了向后兼容而保留

对于新的实现，请使用 /mcp 端点，因为它提供了更好的性能和可靠性。

它是如何工作的

MCP 服务器提供三种主要工具用于数据库交互：

listTables - 获取数据库架构和表信息（所有经过身份验证的用户）
queryDatabase - 执行只读 SQL 查询（所有经过身份验证的用户）
executeDatabase - 执行写操作如 INSERT/UPDATE/DELETE（仅限特权用户）

认证流程：用户通过 GitHub OAuth 认证 → 服务器验证权限 → 根据用户的 GitHub 用户名提供工具。

安全模型：

所有经过身份验证的 GitHub 用户可以读取数据
只有特定的 GitHub 用户名可以写入/修改数据
内置 SQL 注入保护和查询验证

先看一个简单的例子

想在深入了解完整的数据库实现之前先看看一个基本的 MCP 服务器吗？查看 src/simple-math.ts - 一个具有单个 calculate 工具的最小 MCP 服务器，该工具执行基本数学运算（加、减、乘、除）。这个示例演示了核心 MCP 组件：服务器设置、使用 Zod 模式的工具定义以及双传输支持（/mcp 和 /sse 端点）。您可以使用 wrangler dev --config wrangler-simple.jsonc 在本地运行它，并在 http://localhost:8789/mcp 测试。

先决条件

您的机器上安装了 Node.js
一个 Cloudflare 账户（免费层即可）
一个用于 OAuth 设置的 GitHub 账户
一个 PostgreSQL 数据库（本地或托管）

开始使用

第一步：安装 Wrangler CLI

全局安装 Wrangler 以管理您的 Cloudflare Workers：

npm install -g wrangler

第二步：与 Cloudflare 认证

登录到您的 Cloudflare 账户：

wrangler login

这将打开一个浏览器窗口，您可以在其中使用 Cloudflare 账户进行认证。

第三步：克隆和设置

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

环境变量设置

在运行 MCP 服务器之前，您需要配置几个环境变量以进行身份验证和数据库访问。

创建环境变量文件

从示例创建您的 .dev.vars 文件：
```
cp .dev.vars.example .dev.vars
```

在 .dev.vars 中配置所有必需的环境变量：

# GitHub OAuth（用于身份验证）
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_encryption_key

# 数据库连接
DATABASE_URL=postgresql://username:password@localhost:5432/database_name

# 可选：Sentry 监控
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
NODE_ENV=development

获取 GitHub OAuth 凭据

为本地开发创建一个 GitHub OAuth 应用：
- 转到 GitHub 开发者设置
- 点击“新建 OAuth 应用”
- 应用名称：MCP Server (Local Development)
- 主页 URL：http://localhost:8792
- 授权回调 URL：http://localhost:8792/callback
- 点击“注册应用”
复制您的凭据：
- 复制 客户端 ID 并将其粘贴到 .dev.vars 中的 GITHUB_CLIENT_ID
- 点击“生成新的客户端密钥”，复制它，并将其粘贴到 .dev.vars 中的 GITHUB_CLIENT_SECRET

生成加密密钥

生成用于 Cookie 加密的安全随机加密密钥：

openssl rand -hex 32

复制输出并将其粘贴到 .dev. vars 中的 COOKIE_ENCRYPTION_KEY。

数据库设置

设置 PostgreSQL 使用托管服务，例如：
- Supabase（推荐初学者）
- Neon
- 或使用本地 PostgreSQL/Supabase

更新 .dev.vars 中的 DATABASE_URL 以包含您的连接字符串：

DATABASE_URL=postgresql://username:password@host:5432/database_name

连接字符串示例：

本地：postgresql://myuser:mypass@localhost:5432/mydb
Supabase：postgresql://postgres:your-password@db.your-project.supabase.co:5432/postgres

数据库架构设置

MCP 服务器适用于任何 PostgreSQL 数据库架构。它会自动发现：

public 架构中的所有表
列名、类型和约束
主键和索引

测试连接：一旦设置了数据库，您可以通过询问 MCP 服务器“数据库中有哪些表？”来测试它，然后查询这些表以探索您的数据。

本地开发与测试

在本地运行服务器：

wrangler dev

这使得服务器在 http://localhost:8792 上可用

使用 MCP Inspector 测试

使用 MCP Inspector 来测试您的服务器：

安装并运行 Inspector：

npx @modelcontextprotocol/inspector@latest

连接到您的本地服务器：
- 首选：输入 URL：http://localhost:8792/mcp（可流式传输的 HTTP 传输 - 更新、更健壮）
- 替代：输入 URL：http://localhost:8792/sse（SSE 传输 - 向后兼容支持）
- 点击“连接”
- 按照 OAuth 提示进行 GitHub 身份验证
- 连接后，您将看到可用的工具
测试工具：
- 使用 listTables 查看您的数据库结构
- 使用 queryDatabase 运行 SELECT 查询
- 使用 executeDatabase（如果您有写入权限）进行 INSERT/UPDATE/DELETE 操作

生产部署

设置 KV 命名空间

创建 KV 命名空间： wrangler kv namespace create "OAUTH_KV"
更新 wrangler.jsonc 文件中的 KV ID（替换 <Add-KV-ID>）

部署

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

wrangler deploy

在生产环境中创建环境变量

创建一个新的 GitHub OAuth 应用：

对于主页 URL，指定 https://mcp-github-oauth.<your-subdomain>.workers.dev
对于授权回调 URL，指定 https://mcp-github-oauth.<your-subdomain>.workers.dev/callback
记录您的客户端 ID 并生成客户端密钥。
通过 Wrangler 设置所有必需的秘密：

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY  # 使用：openssl rand -hex  32
wrangler secret put DATABASE_URL
wrangler secret put SENTRY_DSN  # 可选（更多关于 Sentry 设置的信息如下）

测试

使用 Inspector 测试远程服务器：

npx @modelcontextprotocol/inspector@latest

输入 https://mcp-github-oauth.<your-subdomain>.workers.dev/mcp（首选）或 https://mcp-github-oauth.<your-subdomain>.workers.dev/sse（遗留），点击连接。完成身份验证流程后，您将看到工具正在工作：

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

数据库工具及访问控制

可用工具

1. `listTables`（所有用户）

目的：发现数据库架构和结构访问：所有经过身份验证的 GitHub 用户用法：始终首先运行此命令以了解您的数据库结构

示例输出：
- 表：users, products, orders
- 列：id (integer), name (varchar), created_at (timestamp)
- 约束和关系

2. `queryDatabase`（所有用户）

目的：执行只读 SQL 查询访问：所有经过身份验证的 GitHub 用户限制：仅允许 SELECT 语句和读操作

-- 允许查询的示例：
SELECT * FROM users WHERE created_at > '2024-01-01';
SELECT COUNT(*) FROM products;
SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id;

3. `executeDatabase`（仅限特权用户）

目的：执行写操作（INSERT, UPDATE, DELETE, DDL）访问：限制为特定 GitHub 用户名功能：包括架构修改在内的完整数据库写入访问

-- 允许操作的示例：
INSERT INTO users (name, email) VALUES ('New User', 'user@example.com');
UPDATE products SET price = 29.99 WHERE id = 1;
DELETE FROM orders WHERE status = 'cancelled';
CREATE TABLE new_table (id SERIAL PRIMARY KEY, data TEXT);

访问控制配置

数据库写入访问由 ALLOWED_USERNAMES 配置中的 GitHub 用户名控制：

// 添加具有数据库写入访问权限的 GitHub 用户名
const ALLOWED_USERNAMES = new Set([
  'yourusername',    // 替换为您自己的 GitHub 用户名
  'teammate1',       // 添加需要写入权限的团队成员
  'database-admin'   // 添加其他可信用户
]);

要更新访问权限：

编辑 src/index.ts 和 src/index_non_sentry.ts
更新 ALLOWED_USERNAMES 集合中的 GitHub 用户名
重新部署 worker：wrangler deploy

典型工作流程

🔍 发现：使用 listTables 了解数据库结构
📊 查询：使用 queryDatabase 读取和分析数据
✏️ 修改：使用 executeDatabase（如果您有写入权限）进行更改

安全特性

SQL 注入保护：所有查询在执行前都会被验证
操作类型检测：自动检测读取与写入操作
用户上下文跟踪：所有操作都记录了 GitHub 用户信息
连接池：高效的数据库连接管理
错误清理：数据库错误在返回给用户之前会被清理

从 Claude Desktop 访问远程 MCP 服务器

打开 Claude Desktop 并导航至设置 -> 开发者 -> 编辑配置。这将打开控制 Claude 可以访问哪些 MCP 服务器的配置文件。

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

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

一旦工具（在 🔨 下）出现在界面中，您可以要求 Claude 与您的数据库互动。示例命令：

“数据库中有哪些表？” → 使用 listTables 工具
“显示过去 30 天内创建的所有用户” → 使用 queryDatabase 工具
“添加一个名为 John 的新用户，电子邮件为 john@example.com” → 使用 executeDatabase 工具（如果您有写入权限）

使用 Claude 和其他 MCP 客户端

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

使用 Cursor 和其他 MCP 客户端

要将 Cursor 与您的 MCP 服务器连接，请选择 Type： "Command" 并在 Command 字段中组合命令和参数字段（例如 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 客户端。

Sentry 集成（可选）

该项目包括可选的 Sentry 集成，用于全面的错误跟踪、性能监控和分布式追踪。有两种版本可用：

src/index.ts - 标准版，无 Sentry
src/index_sentry.ts - 完整的 Sentry 集成版

设置 Sentry

创建 Sentry 账户：如果您没有账户，请在 sentry.io 注册。
创建新项目：在 Sentry 中创建一个新项目，并选择“Cloudflare Workers”作为平台（在右上角搜索）。
获取您的 DSN：从您的 Sentry 项目设置中复制 DSN。

在生产中使用 Sentry

要部署带有 Sentry 监控：

设置 Sentry DSN 密钥：
```
wrangler secret put SENTRY_DSN
```
当提示时输入您的 Sentry DSN。
更新您的 wrangler.toml 以使用带 Sentry 的版本：
```
main = "src/index_sentry.ts"
```
使用 Sentry 部署：
```
wrangler deploy
```

在开发中使用 Sentry

将 Sentry DSN 添加到您的 .dev.vars 文件中：

SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
NODE_ENV=development

启用 Sentry 运行：
```
wrangler dev
```

Sentry 包含的功能

错误跟踪：自动捕获所有错误及其上下文
性能监控：完整请求跟踪，采样率为 100%
用户上下文：自动绑定 GitHub 用户信息到事件
工具追踪：每个 MCP 工具调用都被追踪，带有参数
自定义错误处理：带有事件 ID 的用户友好错误消息
上下文丰富：自动标记和上下文，便于调试

它是如何工作的？

OAuth 提供者

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

认证连接到您服务器的 MCP 客户端
管理与 GitHub 的 OAuth 服务的连接
在 KV 存储中安全存储令牌和认证状态

Durable MCP

Durable MCP 通过 Cloudflare 的 Durable Objects 扩展了基础 MCP 功能，提供