shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

mcp-db-bridge

一个支持MySQL、PostgreSQL和SQLite的MCP服务器，具有细粒度权限控制、多数据库支持和云就绪的SSL/TLS功能，采用适配器模式实现可扩展架构

article

README

🚀 mcp-db-bridge

mcp-db-bridge 是一个支持 MySQL、PostgreSQL 和 SQLite 的 MCP（Model Context Protocol）服务器，具备细粒度权限控制、多数据库支持以及云就绪的 SSL/TLS 功能。它采用适配器模式构建，具有良好的可扩展性。

English | Português

🚀 快速开始

安装

npm install mcp-db-bridge
# 或者
pnpm add mcp-db-bridge

配置示例

MySQL（本地）

# .env
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL（本地）

# .env
DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=mydb

SQLite（内存数据库）

# .env
DB_TYPE=sqlite
SQLITE_DB=:memory:

运行

pnpm build
pnpm start
# 或者
node dist/index.js

✨ 主要特性

  • 🔌 多数据库支持：支持 MySQL、PostgreSQL 和 SQLite。
  • 🏗️ 适配器模式：架构清晰，易于扩展。
  • ☁️ 云就绪：支持 AWS RDS、Google Cloud SQL 和 Azure Database 的 SSL/TLS 连接。
  • 🔒 安全优先：具备只读模式和细粒度的模式权限控制。
  • 🌐 多数据库模式：可同时访问多个模式或数据库。
  • 🔄 事务处理：自动处理 BEGIN/COMMIT/ROLLBACK。
  • 🚀 HTTP 模式：可选的远程 HTTP 服务器（基于 Express）。

📦 安装指南

安装依赖

npm install mcp-db-bridge
# 或者
pnpm add mcp-db-bridge

💻 使用示例

MySQL 搭配 Unix 套接字

DB_TYPE=mysql
MYSQL_SOCKET_PATH=/tmp/mysql.sock
DB_USER=root
DB_PASS=password
DB_NAME=mydb

带权限控制的 PostgreSQL 多数据库模式

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=                                      # 多数据库模式
SCHEMA_INSERT_PERMISSIONS=app_db:true         # app_db 可以插入数据
SCHEMA_UPDATE_PERMISSIONS=app_db:true         # app_db 可以更新数据
SCHEMA_DELETE_PERMISSIONS=app_db:false        # app_db 禁止删除数据

只读模式的 SQLite

DB_TYPE=sqlite
SQLITE_DB=/var/lib/data/production.db
DB_READ_ONLY_MODE=true

带 SSL 的 AWS RDS MySQL

DB_TYPE=mysql
DB_HOST=prod.abc123.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=admin
DB_PASS=secure_password
DB_NAME=production
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
ALLOW_INSERT_OPERATION=false
ALLOW_UPDATE_OPERATION=false
ALLOW_DELETE_OPERATION=false
ALLOW_DDL_OPERATION=false

📚 详细文档

配置

数据库类型

DB_TYPE=mysql          # MySQL
DB_TYPE=postgresql     # PostgreSQL
DB_TYPE=sqlite         # SQLite

连接设置

通用设置（适用于所有数据库）

DB_HOST=127.0.0.1
DB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432
DB_USER=root
DB_PASS=password
DB_NAME=mydb           # 留空表示启用多数据库模式
DB_CONNECTION_LIMIT=10

MySQL 特定设置（向后兼容）

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASS=password
MYSQL_DB=mydb
MYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unix 套接字（优先于 host/port）

PostgreSQL 特定设置

POSTGRESQL_HOST=127.0.0.1
POSTGRESQL_PORT=5432
POSTGRESQL_DB=mydb

SQLite 特定设置

SQLITE_DB=:memory:              # 内存数据库
SQLITE_DB=/var/lib/app/data.db  # 文件数据库

安全与权限

只读模式

在应用层阻止所有写操作：

DB_READ_ONLY_MODE=true

全局写权限

按操作类型进行细粒度的全局控制：

ALLOW_INSERT_OPERATION=true   # 允许 INSERT 操作
ALLOW_UPDATE_OPERATION=true   # 允许 UPDATE 操作
ALLOW_DELETE_OPERATION=false  # 阻止 DELETE 操作
ALLOW_DDL_OPERATION=false     # 阻止 CREATE/ALTER/DROP/TRUNCATE 操作

模式特定权限

覆盖特定模式的全局权限：

# 格式: "schema1:true,schema2:false,schema3:true"
SCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false
SCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false

工作原理：

  • 如果模式有特定权限，则使用该权限。
  • 否则，使用全局标志。

示例：

# 全局设置：禁止 INSERT 操作
ALLOW_INSERT_OPERATION=false

# test_db 可以插入数据，prod_db 禁止插入数据
SCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false

# 结果：
# - 在 test_db 上执行 INSERT 操作：✅ 允许（使用模式权限）
# - 在 prod_db 上执行 INSERT 操作：❌ 禁止（使用模式权限）
# - 在 other_db 上执行 INSERT 操作：❌ 禁止（使用全局权限）

多数据库模式

通过单个连接访问多个数据库或模式。

激活

将 DB_NAME 留空（仅适用于 MySQL/PostgreSQL）：

DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=                # 留空表示启用多数据库模式

写保护

默认情况下，为了安全起见，多数据库模式为只读模式。若要允许写操作：

MULTI_DB_WRITE_MODE=true  # ⚠️ 谨慎使用！

建议：使用 SCHEMA_*_PERMISSIONS 进行细粒度控制，而不是直接设置 MULTI_DB_WRITE_MODE=true。

完整示例

# 带细粒度权限的多数据库模式
DB_TYPE=mysql
DB_NAME=                                    # 多数据库模式
ALLOW_INSERT_OPERATION=false                # 全局设置：禁止插入
SCHEMA_INSERT_PERMISSIONS=test_db:true      # 例外：test_db 可以插入数据
SCHEMA_UPDATE_PERMISSIONS=test_db:true      # 例外：test_db 可以更新数据
SCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db 禁止删除数据
SCHEMA_DDL_PERMISSIONS=test_db:true         # test_db 允许 DDL 操作

云数据库的 SSL/TLS 配置

AWS RDS（MySQL/PostgreSQL）

DB_TYPE=mysql
DB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
# 可选：DB_SSL_CA=/path/to/aws-rds-ca-cert.pem

Google Cloud SQL（PostgreSQL）

DB_TYPE=postgresql
DB_HOST=34.123.45.67
DB_PORT=5432
DB_SSL=true
DB_SSL_CA=/path/to/server-ca.pem
DB_SSL_CERT=/path/to/client-cert.pem
DB_SSL_KEY=/path/to/client-key.pem

Azure Database for MySQL

DB_TYPE=mysql
DB_HOST=myserver.mysql.database.azure.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true

远程 MCP（HTTP 服务器）

通过 HTTP 运行 MCP 服务器并进行身份验证：

# .env
IS_REMOTE_MCP=true
REMOTE_SECRET_KEY=your-secret-key-here
PORT=3000

端点：POST http://localhost:3000/mcp

请求头：Authorization: Bearer your-secret-key-here

🔧 技术细节

架构

src/
├── db/
│   ├── adapters/
│   │   ├── types.ts              # 接口和类型定义
│   │   ├── factory.ts            # 工厂模式
│   │   ├── mysql.adapter.ts      # 通过 mysql2 实现的 MySQL 适配器
│   │   ├── postgresql.adapter.ts # 通过 pg 实现的 PostgreSQL 适配器
│   │   └── sqlite.adapter.ts     # 通过 better-sqlite3 实现的 SQLite 适配器
│   ├── index.ts                  # 核心查询处理程序
│   ├── utils.ts                  # SQL 解析（使用 node-sql-parser）
│   └── permissions.ts            # 模式权限检查
├── config/
│   └── index.ts                  # 环境配置
├── utils/
│   └── index.ts                  # 日志记录和工具函数
└── types/
    └── index.ts                  # 类型定义

适配器模式

每个适配器都实现了 DatabaseAdapter 接口：

export interface DatabaseAdapter {
  readonly type: DatabaseType;
  createPool(config: ConnectionConfig): Promise<DatabasePool>;
  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;
  setReadOnly(connection: DatabaseConnection): Promise<void>;
  unsetReadOnly(connection: DatabaseConnection): Promise<void>;
  normalizeResult(result: any): NormalizedResult;
  supportsReadOnlyMode(): boolean;
}

事务流程

读操作：

BEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE

写操作：

BEGIN → QUERY → COMMIT (或在出错时 ROLLBACK)

📄 许可证

本项目采用 MIT 许可证。

致谢

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client