Cloudflare 远程 PostgreSQL 数据库 MCP 服务器 + GitHub OAuth
这是一个 模型上下文协议（MCP） 使您能够使用的服务器 与您的 PostgreSQL 数据库聊天可作为通过Cloudflare部署的远程MCP服务器，使用GitHub OAuth进行身份验证。这是一个已准备好投入生产的MCP。
主要特点
- 🗄️ 与Lifespan的数据库集成所有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 - 一个带有单一（功能/组件）的最小化MCP服务器 calculate 一个执行基本数学运算（加、减、乘、除）的工具。此示例展示了MCP的核心组件：服务器设置、使用Zod模式定义工具，以及双传输支持（/mcp 并且 /sse （终端点）。您可以在本地运行它，使用 wrangler dev --config wrangler-simple.jsonc 并在（指定时间或条件下）进行测试 http://localhost:8789/mcp。
先决条件
- 您的机器上已安装 Node.js
- 一个Cloudflare账户（免费套餐即可）
- 用于OAuth设置的GitHub账户
- 一个PostgreSQL数据库（本地或托管）
入门指南
步骤1：安装Wrangler CLI
全局安装 Wrangler 以管理您的 Cloudflare Workers：
npm install -g wrangler步骤2：使用Cloudflare进行身份验证
登录您的Cloudflare账户：
wrangler login这将打开一个浏览器窗口，您可以在其中使用您的 Cloudflare 帐户进行身份验证。
步骤3：克隆并设置
直接克隆仓库并安装依赖项： npm install。
环境变量设置
在运行MCP服务器之前，您需要配置几个环境变量以进行身份验证和数据库访问。
创建环境变量文件
- 创建你的
.dev.vars文件 从例子中可以看出：
cp .dev.vars.example .dev.vars- 配置所有必需的环境变量 在里面
.dev.vars:
# GitHub OAuth (for authentication)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_encryption_key
# Database Connection
DATABASE_URL=postgresql://username:password@localhost:5432/database_name
# Optional: Sentry monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
NODE_ENV=development获取GitHub OAuth凭据
- 创建一个GitHub OAuth应用程序 用于本地开发：
- 首选 - 点击“新建OAuth应用” - 应用程序名称: MCP Server (Local Development) - 主页网址： http://localhost:8792 - 授权回调URL： http://localhost:8792/callback - 点击“注册应用”
- 复制您的凭据:
- 复制 客户端ID 并将其粘贴为 GITHUB_CLIENT_ID 在 .dev.vars - 点击“生成新的客户端密钥”，复制它，然后粘贴为 GITHUB_CLIENT_SECRET 在 .dev.vars
生成加密密钥
为cookie加密生成一个安全的随机加密密钥：
openssl rand -hex 32复制输出内容并粘贴为 COOKIE_ENCRYPTION_KEY 在 .dev.vars.
数据库设置
- 设置 PostgreSQL 使用类似以下的托管服务：
- Supabase（可译为“苏帕巴斯”或根据具体语境保留原名，因其是一个特定的软件或服务名称，直接翻译可能不常见） （推荐给初学者） - 霓虹灯 - 或者使用本地的 PostgreSQL/Supabase
- 更新DATABASE_URL 在
.dev.vars使用您的连接字符串：
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：
npx @modelcontextprotocol/inspector@latest- 连接到您的本地服务器：
- 优选的；更喜欢的输入网址： http://localhost:8792/mcp (可流式传输的HTTP传输方式 - 更新、更健壮) - 替代方案输入网址： http://localhost:8792/sse (SSE传输 - 向后兼容支持) - 点击“连接” - 按照OAuth提示进行GitHub身份验证 - 一旦连接成功，您将看到可用的工具
- 测试工具:
- 使用 listTables 查看您的数据库结构 - 使用 queryDatabase 执行SELECT查询 - 使用 executeDatabase （如果您有写入权限）进行插入/更新/删除操作
生产部署
设置一个KV命名空间
- 创建KV命名空间：
wrangler kv namespace create "OAUTH_KV"
- 更新
wrangler.jsonc带有KV ID的文件（替换 )
部署
部署MCP服务器，使其在workers.dev域名下可用
wrangler deploy在生产环境中创建环境变量
创建一个新（的） ：
- 对于主页URL，请指定
https://mcp-github-oauth..workers.dev - 对于授权回调URL，请指定
https://mcp-github-oauth..workers.dev/callback - 记下您的客户端ID并生成一个客户端密钥。
- 通过 Wrangler 设置所有必需的密钥：
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # use: openssl rand -hex 32
wrangler secret put DATABASE_URL
wrangler secret put SENTRY_DSN # optional (more on Sentry setup below)测试
使用以下方法测试远程服务器 检查员：
npx @modelcontextprotocol/inspector@latest输入 https://mcp-github-oauth..workers.dev/mcp （首选）或 https://mcp-github-oauth..workers.dev/sse （旧版）并点击连接。一旦您完成身份验证流程，您就会看到工具正在工作：
您现在已经部署了一个远程MCP服务器！
数据库工具与访问控制
可用工具
1. listTables （所有用户）
目的发现数据库模式和结构\ 访问所有经过验证的GitHub用户\ 使用始终先运行此命令以了解您的数据库结构
Example output:
- Tables: users, products, orders
- Columns: id (integer), name (varchar), created_at (timestamp)
- Constraints and relationships2. queryDatabase （所有用户）
目的执行只读SQL查询\ 访问所有已认证的GitHub用户\ 限制仅允许使用SELECT语句和读取操作
-- Examples of allowed queries:
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用户名\ 能力完全数据库写入访问权限，包括模式修改
-- Examples of allowed operations:
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);访问控制配置
数据库写入访问权限由GitHub用户名控制 ALLOWED_USERNAMES 配置：
// Add GitHub usernames for database write access
const ALLOWED_USERNAMES = new Set([
'yourusername', // Replace with your GitHub username
'teammate1', // Add team members who need write access
'database-admin' // Add other trusted users
]);更新访问权限：
- 编辑
src/index.ts并且src/index_non_sentry.ts - 更新
ALLOWED_USERNAMES设置GitHub用户名 - 重新部署工作节点：
wrangler deploy
典型工作流程
- 🔍 发现使用
listTables了解数据库结构 - 📊 查询使用
queryDatabase阅读并分析数据 - ✏️ 修改使用
executeDatabase（如果你有写入权限）进行更改
安全特性
- SQL注入防护所有查询在执行前均经过验证
- 操作类型检测自动检测读取与写入操作
- 用户上下文追踪所有操作均记录在案，并附有GitHub用户信息
- 连接池高效的数据库连接管理
- 错误净化（或错误处理/错误清理）数据库错误在返回给用户之前已被清除
从Claude桌面访问远程MCP服务器
打开Claude桌面版，导航至设置 -> 开发者 -> 编辑配置。这将打开控制Claude可以访问哪些MCP服务器的配置文件。
将内容替换为以下配置。一旦您重启Claude桌面应用程序，将打开一个浏览器窗口，显示您的OAuth登录页面。完成身份验证流程以授予Claude访问您的MCP服务器的权限。授权后，工具将可供您使用。
{
"mcpServers": {
"math": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-github-oauth..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 字段，将命令字段和参数字段合并为一个（例如。 npx mcp-remote https://..workers.dev/sse）。
请注意，虽然 Cursor 支持 HTTP+SSE 服务器，但它不支持身份验证，因此您仍然需要使用 mcp-remote （并且使用STDIO服务器，而不是HTTP服务器）。
你可以通过打开客户端的配置文件，添加用于设置Claude的相同JSON配置，然后重启MCP客户端，将你的MCP服务器连接到其他MCP客户端，如Windsurf。
Sentry 集成（可选）
此项目包含可选的Sentry集成，用于全面的错误追踪、性能监控和分布式追踪。提供两个版本：
src/index.ts- 标准版，不含Sentrysrc/index_sentry.ts- 与Sentry完全集成的版本
设置Sentry
- 创建一个Sentry账户在……注册 sentry.io（可译为“森特里点”或根据具体语境保留原名，因为“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）存储中安全地存储令牌和认证状态
耐用型MCP（多路复用器控制器/模块，具体含义根据上下文确定）
持久化MCP通过Cloudflare的持久化对象（Durable Objects）扩展了基础MCP的功能，提供了：
- 为您的MCP服务器提供持久状态管理
- 在请求之间安全地存储认证上下文
- 通过……访问经过验证的用户信息
this.props - 根据用户身份支持有条件地提供工具可用性
MCP 远程
MCP Remote库使您的服务器能够暴露工具，这些工具可以被MCP客户端（如Inspector）调用。它
- 定义客户端与您的服务器之间的通信协议
- 提供了一种结构化的方式来定义工具
- 处理请求和响应的序列化与反序列化
- 维护客户端与您的服务器之间的服务器发送事件（SSE）连接
测试
这个项目包括全面的单元测试，涵盖了所有主要功能：
npm test # Run all tests
npm run test:ui # Run tests with UI该测试套件涵盖了数据库安全、工具注册、权限处理以及响应格式化，并对外部依赖进行了适当的模拟。