MCP数据库桥接器

Name: MCP数据库桥接器
Author: LucasSiqueiraSurreco

作者：LucasSiqueiraSurreco2 星标更新：2025-10-10

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

项目介绍

mcp-db-bridge

English | Português

中文

适用于MySQL、PostgreSQL及SQLite的MCP（模型上下文协议）服务器，具有细粒度权限、多数据库支持以及云就绪SSL/TLS。采用适配器模式构建以实现扩展性。

特性

🔌 多数据库：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（本地）

# .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

配置

数据库类型

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套接字（优先于主机/端口）

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：阻止DELETE
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      # MySQL通过mysql2
│   │   ├── postgresql.adapter.ts # PostgreSQL通过pg
│   │   └── sqlite.adapter.ts     # SQLite通过better-sqlite3
│   ├── 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)

示例

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：阻止DELETE

SQLite只读模式

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

AWS RDS MySQL带SSL

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

开发

pnpm dev              # 在开发模式下运行（tsx）
pnpm build            # 编译TypeScript
pnpm watch            # 监视模式
pnpm exec             # 构建+运行使用.env

测试

pnpm test              # 运行所有测试（设置+vitest运行）
pnpm test:watch        # 监视模式
pnpm test:unit         # 仅单元测试
pnpm test:integration  # 集成测试（MySQL，套接字，权限）
pnpm test:e2e          # 端到端测试
pnpm test:coverage     # 覆盖率报告

测试结构：

tests/
├── unit/           # 隔离函数（查询解析，工具）
├── integration/    # 实际数据库操作
└── e2e/           # 完整的MCP服务器工作流

性能调整

连接池

DB_CONNECTION_LIMIT=20  # 默认：10

禁用只读事务（MySQL）

⚠️ 不推荐 - 减少安全性：

MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true

环境变量参考

核心数据库设置

变量	描述	默认值	示例
`DB_TYPE`	数据库类型	`mysql`	`mysql`, `postgresql`, `sqlite`
`DB_HOST`	数据库主机	`127.0.0.1`	`localhost`, `db.example.com`
`DB_PORT`	数据库端口	`3306`	`3306`（MySQL），`5432`（PostgreSQL）
`DB_USER`	数据库用户	`root`	`admin`, `postgres`
`DB_PASS`	数据库密码	`""`	`secure_password`
`DB_NAME`	数据库名称	`undefined`	`mydb`, `""`（多数据库）
`DB_CONNECTION_LIMIT`	连接池大小	`10`	`20`

安全设置

变量	描述	默认值	值
`DB_READ_ONLY_MODE`	全局只读模式	`false`	`true`, `false`
`ALLOW_INSERT_OPERATION`	全局INSERT权限	`false`	`true`, `false`
`ALLOW_UPDATE_OPERATION`	全局UPDATE权限	`false`	`true`, `false`
`ALLOW_DELETE_OPERATION`	全局DELETE权限	`false`	`true`, `false`
`ALLOW_DDL_OPERATION`	全局DDL权限	`false`	`true`, `false`
`MULTI_DB_WRITE_MODE`	允许多数据库写入	`false`	`true`, `false`

模式权限

变量	格式	示例
`SCHEMA_INSERT_PERMISSIONS`	`schema:bool,schema:bool`	`test_db:true,prod_db:false`
`SCHEMA_UPDATE_PERMISSIONS`	`schema:bool,schema:bool`	`test_db:true,prod_db:false`
`SCHEMA_DELETE_PERMISSIONS`	`schema:bool,schema:bool`	`test_db:false,prod_db:false`
`SCHEMA_DDL_PERMISSIONS`	`schema:bool,schema:bool`	`test_db:true,prod_db:false`

SSL/TLS设置

变量	描述	是否必需	示例
`DB_SSL`	启用SSL/TLS	云数据库	`true`, `false`
`DB_SSL_REJECT_UNAUTHORIZED`	严格的SSL验证	生产环境	`true`, `false`
`DB_SSL_CA`	CA证书路径	云SQL	`/path/to/ca.pem`
`DB_SSL_CERT`	客户端证书	云SQL	`/path/to/cert.pem`
`DB_SSL_KEY`	客户端密钥	云SQL	`/path/to/key.pem`

远程MCP设置

变量	描述	是否必需	示例
`IS_REMOTE_MCP`	启用HTTP模式	不需要	`true`, `false`
`REMOTE_SECRET_KEY`	认证令牌	如果远程	`your-secret-key`
`PORT`	HTTP服务器端口	不需要	`3000`

故障排除

连接错误

MySQL套接字未找到：

# 检查套接字路径
sudo mysql -u root -p -e "SELECT @@socket;"

# 设置在.env
MYSQL_SOCKET_PATH=/var/run/mysqld/mysqld.sock

PostgreSQL连接被拒绝：

# 检查PostgreSQL是否正在运行
sudo systemctl status postgresql

# 检查端口
sudo netstat -tulpn | grep 5432

权限错误

“只读模式不允许的操作”：

# 检查全局只读模式
DB_READ_ONLY_MODE=false

# 检查多数据库模式
MULTI_DB_WRITE_MODE=true  # 如需

# 或使用模式权限
SCHEMA_INSERT_PERMISSIONS=mydb:true

“模式'mydb'不允许INSERT”：

# 检查全局权限
ALLOW_INSERT_OPERATION=true

# 或添加模式例外
SCHEMA_INSERT_PERMISSIONS=mydb:true

许可

MIT

致谢

mcp-server-mysql: @benborla