db-mcp

一个轻量级 MCP（Model Context Protocol）数据库服务器。它通过 stdio 与 MCP 客户端通信，支持在运行时动态打开 PostgreSQL、MySQL 和 MongoDB 连接，并执行 SQL 或 MongoDB command。

特性

• 动态连接：内置 connect 工具，可在会话中按需创建或替换 PostgreSQL / MySQL / MongoDB 连接。

• 执行 SQL：execute_sql 工具支持位置化参数绑定，避免拼接注入。

• 执行 MongoDB command：execute_mongodb 接收通用 command 文档或 query Extended JSON 字符串，不限制为固定 CRUD 方法。

• 事务控制：提供 begin_transaction、commit_transaction、rollback_transaction 三个工具。

• 关闭连接：close_connection 用于主动释放指定或当前连接。

• 只读模式：支持 --readOnly / --readonly 启动参数。

• 自动识别 SQL 类型：读（read）、写（write）、事务（transaction）、未知（unknown）。

• 只读模式仅放行 read 类型，write、transaction、unknown 全部拒绝；MongoDB aggregate 中包含 $out / $merge 时按写操作处理。

Related MCP server: mcp-db-server

安装

环境要求：Node.js 20+。

npm install
npm run build

运行

默认启动（可写）：

npx db-mcp

只读模式：

npx db-mcp --readOnly

开发模式（tsx 直接执行源码）：

npm run dev -- --readOnly

在 MCP 客户端中配置

在客户端的 MCP 配置中新增一个 server 条目即可。

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/db-mcp/dist/index.js", "--readOnly"]
    }
  }
}

如果不启用只读模式，去掉 --readOnly 即可。

工具列表

connectionId 参数在所有工具中都是可选的：不传时使用最近一次 connect 创建的连接。

这些工具的 MCP 描述中内置了面向客户端 AI 的使用提示。客户端 AI 会看到各工具的 description 和参数 schema description，用于决定应该生成 SQL、MongoDB command 对象，还是 Extended JSON 查询字符串。

工具详解

connect

创建一个新连接，或在 id 冲突时替换已有连接。id 不传时默认为 default。

PostgreSQL 示例（使用连接字符串）：

{
  "id": "analytics",
  "type": "postgres",
  "connectionString": "postgres://user:password@localhost:5432/app"
}

PostgreSQL 示例（使用离散字段）：

{
  "id": "app_pg",
  "type": "postgres",
  "host": "localhost",
  "port": 5432,
  "database": "app",
  "user": "app",
  "password": "secret",
  "ssl": false
}

MySQL 示例：

{
  "id": "app_mysql",
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "app",
  "user": "root",
  "password": "secret"
}

MongoDB 示例（使用连接字符串）：

{
  "id": "app_mongo",
  "type": "mongodb",
  "connectionString": "mongodb://user:password@localhost:27017/app",
  "database": "app"
}

MongoDB 示例（使用离散字段）：

{
  "id": "app_mongo",
  "type": "mongodb",
  "host": "localhost",
  "port": 27017,
  "database": "app",
  "user": "root",
  "password": "secret",
  "ssl": false
}

execute_sql

执行单条 SQL，并支持位置化参数。参数占位符与底层驱动一致：

• PostgreSQL 使用 $1、$2 …

• MySQL 使用 ?

内置提示会要求客户端 AI：

• 生成普通 SQL，不生成 MongoDB 语法。

• 使用 params 绑定参数，不把用户输入拼接进 SQL 字符串。

• PostgreSQL 使用 $1、$2 等占位符。

• MySQL 使用 ? 占位符。

• 只读模式下只生成读查询。

PostgreSQL 示例：

{
  "connectionId": "analytics",
  "sql": "select id, email from users where id = $1",
  "params": [1]
}

MySQL 示例：

{
  "connectionId": "app_mysql",
  "sql": "select id, email from users where id = ?",
  "params": [1]
}

返回结构示例：

{
  "statementType": "read",
  "rows": [{ "id": 1, "email": "a@example.com" }],
  "fields": ["id", "email"],
  "rowCount": 1
}

execute_mongodb

执行 MongoDB 原生命令。command、query、commandJson 三选一：

• command：直接传 JSON 对象。

• query：传 Extended JSON 字符串，适合让 AI 直接生成完整 MongoDB command 查询语句。

• commandJson：query 的兼容别名，适合 $oid、$date 等 BSON 类型。

内置提示会要求客户端 AI：

• 使用 MongoDB command，不生成 db.users.find(...) 这类 Mongo shell JavaScript。

• 查询字符串必须是合法 Extended JSON。

• find 使用 {"find":"users","filter":{},"limit":10} 这类 command。

• aggregate 使用 {"aggregate":"orders","pipeline":[...],"cursor":{}}，并包含 cursor。

• _id、日期等 BSON 值使用 $oid、$date 等 Extended JSON。

• 只读模式下避免写命令，且不要使用包含 $out / $merge 的聚合。

查询示例：

{
  "connectionId": "app_mongo",
  "database": "app",
  "command": {
    "find": "users",
    "filter": { "active": true },
    "limit": 10
  }
}

聚合示例：

{
  "connectionId": "app_mongo",
  "database": "app",
  "command": {
    "aggregate": "orders",
    "pipeline": [
      { "$match": { "status": "paid" } },
      { "$group": { "_id": "$userId", "total": { "$sum": "$amount" } } }
    ],
    "cursor": {}
  }
}

Extended JSON 示例：

{
  "connectionId": "app_mongo",
  "database": "app",
  "query": "{\"find\":\"users\",\"filter\":{\"_id\":{\"$oid\":\"66f000000000000000000001\"}},\"limit\":1}"
}

写入也通过同一个工具传 MongoDB command：

{
  "connectionId": "app_mongo",
  "database": "app",
  "command": {
    "insert": "users",
    "documents": [{ "email": "a@example.com", "active": true }]
  }
}

只读模式下会拒绝明确写操作和未知命令；aggregate 管道包含 $out 或 $merge 时也会被拒绝。

事务控制

begin_transaction、commit_transaction、rollback_transaction 的入参一致，仅支持 PostgreSQL / MySQL 连接：

{ "connectionId": "analytics" }

调用顺序示例：先 begin_transaction，再连续 execute_sql 执行若干写语句，最后根据结果调用 commit_transaction 或 rollback_transaction。

注意：

• 一个连接同一时间只能存在一个事务，重复开启会报错。

• 只读模式下，三个事务工具都会被拒绝。

• 进程退出时会自动关闭所有连接。

close_connection

关闭指定连接；不传 connectionId 时关闭当前默认连接。

{ "connectionId": "analytics" }

SQL 类型识别

服务器会跳过空白、-- 行注释、/* ... */ 块注释以及引号/反引号包裹的字符串，再判断第一个关键字：

• 读（read）：select、show、describe、desc、explain、values，以及不包含写关键字的 with 查询。

• 写（write）：insert、update、delete、merge、replace、create、alter、drop、truncate、grant、revoke、call、do、copy、load、set、reset、analyze、vacuum、refresh。

• 事务（transaction）：begin、start、commit、rollback、savepoint、release。

• 未知（unknown）：以上均不匹配，例如以 @、变量、方言特有语法开头的语句。

补充规则：

• with 查询中若出现写关键字（insert / update / delete / merge / replace 等），按写处理。

• select ... for update、select ... for share、select ... into ... 等具有副作用的形态，按写处理。

• 只读模式下仅放行 read 类型。

MongoDB command 类型识别

execute_mongodb 通过 command 文档的第一个键判断操作类型：

• 读（read）：例如 find、aggregate、count、distinct、listCollections、listIndexes、dbStats、collStats、serverStatus、ping。

• 写（write）：例如 insert、update、delete、findAndModify、create、drop、createIndexes、dropIndexes、renameCollection。

• 未知（unknown）：不在内置列表中的命令。

• aggregate 管道中包含 $out 或 $merge 时按写操作处理。

• explain 只有包裹的命令可判定为读操作时才按读处理。

常见问题

• 启动报错 “No database connection is open”：先调用 connect 成功建立连接再执行 SQL。

• 执行写语句被拒绝：检查是否在只读模式下；可在 MCP 启动参数中移除 --readOnly。

• MongoDB 命令被判定为 unknown：只读模式下未知命令会被拒绝；可改用明确的 read command，或在可写模式下执行。

• 事务相关报错 “No transaction is open”：只有调用过 begin_transaction 后才能 commit / rollback。

• 关闭进程后连接未释放：通常不需要关心；如果长时间持有连接，建议在每次会话结束前调用 close_connection。

开发

npm run dev      # 监听源码变更并以 tsx 执行
npm run build    # 类型检查并输出 dist
npm start        # 执行 dist/index.js

源码结构：

• src/index.ts：MCP server 入口、工具注册、只读模式开关。

• src/db.ts：连接管理、SQL 执行、MongoDB command 执行、事务控制。

• src/sqlClassifier.ts：SQL 类型识别。

许可

MIT