Cloudflare远程PostgreSQL数据库MCP服务器+GitHub OAuth
这是一个 模型上下文协议（MCP） 服务器，使您能够 与您的PostgreSQL数据库聊天，可通过Cloudflare使用GitHub OAuth作为远程MCP服务器部署。这是生产就绪的MCP。
主要特点
- 🗄️ 数据库与Lifespan的集成：所有MCP工具调用的直接PostgreSQL数据库连接
- 🛠️ 模块化、单用途工具：遵循围绕MCP工具及其描述的最佳实践
- 🔐 基于角色的访问：基于GitHub用户名的数据库写入操作权限
- 📊 架构发现：自动检索表和列信息
- 🛡️ SQL注入保护：内置验证和消毒
- 📈 监控：可选的Sentry集成用于生产监控
- ☁️ 云原生：技术支持 Cloudflare员工 全球范围
模块化架构
此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服务器的最小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检验员测试
使用 MCP检查员 要测试您的服务器：
- 安装并运行检查器:
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的文件（替换 )
部署
部署MCP服务器，使其在workers.dev域上可用
wrangler deploy在生产中创建环境变量
创建新 :
- 对于主页URL，请指定
https://mcp-github-oauth..workers.dev - 对于授权回调URL，请指定
https://mcp-github-oauth..workers.dev/callback - 记下您的客户端ID并生成客户端密钥。
- 通过牧马人设置所有必需的秘密：
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 Desktop访问远程MCP服务器
打开克劳德桌面，导航到设置->开发人员->编辑配置。这将打开控制Claude可以访问哪些MCP服务器的配置文件。
用以下配置替换内容。重新启动Claude Desktop后，将打开一个浏览器窗口，显示您的OAuth登录页面。完成身份验证流程，授予Claude访问您的MCP服务器的权限。授予访问权限后，这些工具将可供您使用。
{
"mcpServers": {
"math": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-github-oauth..workers.dev/mcp"
]
}
}
}一旦工具（下🔨) 在界面中显示，您可以让Claude与您的数据库进行交互。命令示例：
- “数据库中有哪些表可用？” → Uses
listTables工具 - “显示过去30天内创建的所有用户” → Uses
queryDatabase工具 - “通过电子邮件添加一个名为John的新用户john@example.com" → Uses
executeDatabase工具（如果您有写权限）
使用Claude和其他MCP客户端
使用Claude连接到远程MCP服务器时，您可能会看到一些错误消息。这是因为Claude Desktop还不支持远程MCP服务器，所以有时会感到困惑。要验证MCP服务器是否已连接，请将鼠标悬停在🔨 克劳德界面右下角的图标。你应该在那里看到你的工具。
使用游标和其他MCP客户端
要将Cursor与MCP服务器连接，请选择 Type：“命令”和 Command 字段，将命令和args字段组合成一个（例如。 npx mcp-remote https://..workers.dev/sse).
请注意，虽然Cursor支持HTTP+SSE服务器，但它不支持身份验证，因此您仍然需要使用 mcp-remote （并且使用STDIO服务器，而不是HTTP服务器）。
您可以通过打开客户端的配置文件，添加用于Claude设置的相同JSON，并重新启动MCP客户端，将MCP服务器连接到其他MCP客户端，如Windsurf。
哨兵集成（可选）
该项目包括可选的Sentry集成，用于全面的错误跟踪、性能监控和分布式跟踪。有两个版本可供选择：
src/index.ts-不带Sentry的标准版src/index_sentry.ts-具有完整Sentry集成的版本
设立哨兵
- 创建哨兵帐户：注册地址： sentry.io 如果你没有账户。
- 创建新项目：在Sentry中创建一个新项目，并选择“Cloudflare Workers”作为平台（在右上角搜索）。
- 获取您的DSN：从Sentry项目设置中复制DSN。
在生产中使用Sentry
要部署哨兵监控：
- 设置哨兵DSN秘密:
wrangler secret put SENTRY_DSN出现提示时输入您的哨兵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- 启用哨兵功能运行:
wrangler dev包括哨兵功能
- 错误跟踪：自动捕获所有带有上下文的错误
- 性能监控：100%采样率的完整请求跟踪
- 用户上下文：自动将GitHub用户信息绑定到事件
- 工具跟踪：每个MCP工具调用都有参数跟踪
- 自定义错误处理：带有事件ID的用户友好错误消息
- 上下文丰富：自动标记和上下文，以便更好地调试
它是如何工作的？
OAuth提供者
OAuth Provider库是Cloudflare Workers的完整OAuth 2.1服务器实现。它处理OAuth流的复杂性，包括令牌发放、验证和管理。在这个项目中，它扮演着双重角色：
- 对连接到服务器的MCP客户端进行身份验证
- 管理与GitHub OAuth服务的连接
- 在KV存储器中安全存储令牌和身份验证状态
耐用MCP
Durable MCP通过Cloudflare的Durable Objects扩展了基本MCP功能，提供：
- MCP服务器的持久状态管理
- 请求之间身份验证上下文的安全存储
- 通过以下方式访问经过身份验证的用户信息
this.props - 支持基于用户身份的有条件工具可用性
MCP远程
MCP Remote库使您的服务器能够公开可由MCP客户端（如检查器）调用的工具。它
- 定义客户端和服务器之间的通信协议
- 提供了一种结构化的方法来定义工具
- 处理请求和响应的序列化和反序列化
- 维护客户端和服务器之间的服务器发送事件（SSE）连接
测试
该项目包括涵盖所有主要功能的全面单元测试：
npm test # Run all tests
npm run test:ui # Run tests with UI测试套件涵盖了数据库安全、工具注册、权限处理和响应格式，并对外部依赖关系进行了适当的模拟。