MCP DB Connect

MCP DB Connect

通用 MCP 服务，支持以只读优先的方式访问 Oracle Database、Microsoft SQL Server、PostgreSQL、MySQL/MariaDB、SQLite、MongoDB 和 Qdrant 向量搜索。

本项目面向支持 Model Context Protocol 的 AI 工具。项目可以安装本工具、提供 YAML 配置，并向其 AI 客户端开放安全的数据库工具。

Oracle 连接默认使用 Node.js oracledb Thin 模式，因此大多数数据库不需要 Oracle Instant Client。某些 Oracle 数据库使用 Thin 模式无法处理的 NCHAR 字符集；这些数据库需要使用搭配 Oracle Client 库的 Oracle Thick 模式。

默认情况下，从项目目录运行命令时会自动使用：

• mcp-db.local.yml，然后是 mcp-db.yml，再然后是 mcp-db.yaml
• .env

功能

• 支持 Oracle、MSSQL、PostgreSQL、MySQL/MariaDB、SQLite、MongoDB 和 Qdrant 的连接器
• 在一个配置文件中配置多个命名连接
• 默认只读
• 禁止 SQL 多语句
• 只读模式下禁止 MongoDB $out 和 $merge
• 行数限制和查询超时
• 查询结果以 Markdown 表格形式输出
• 架构／表允许列表和拒绝列表
• 敏感字段脱敏
• JSONL 审计日志
• 面向 AI 客户端和数据库连接的交互式设置向导
• 用于设置、初始化、验证、测试连接以及启动 stdio／HTTP 服务的 CLI
• Docker 镜像（多阶段 Dockerfile，发布时推送至 GHCR）

安装

1. 安装软件包

Node / TypeScript 项目（本地安装）：

npm install --save-dev mcp-db-connect

.NET、Python 或其他非 Node 项目（全局安装）：

npm install -g mcp-db-connect

2. 运行设置向导

npx mcp-db-connect setup

向导会询问要配置哪些 AI 客户端和数据库，然后要求为每个数据库提供一个连接字符串（与你的数据库主机、托管服务商或现有应用配置提供的字符串相同），并自动写入所有配置文件。

3. 测试连接

npx mcp-db-connect test-connections

完成后，你的 AI 客户端便已连接到数据库。

向导会创建的内容

mcp-db.local.yml       # database connection config
.env                   # local secrets
.gitignore             # keeps secrets and local config out of git
.mcp.json              # Claude Code MCP config (if selected)
.codex/config.toml     # Codex CLI config (if selected)
.gemini/settings.json  # Gemini CLI config (if selected)
.kimi/mcp.json         # Kimi CLI config (if selected)

其他设置选项

使用明确的标志跳过向导：

npx mcp-db-connect setup --ai claude,codex --db mssql,mongodb

覆盖现有配置项：

npx mcp-db-connect setup --force

启动 HTTP MCP 端点，而不是 stdio：

npx mcp-db-connect serve-http --host 127.0.0.1 --port 3000
npx mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY

AI 客户端示例

以下示例均假设 AI CLI 从应用项目根目录启动。

Claude Code CLI

推荐的自动设置方式：

mcp-db-connect setup --ai claude --db mssql

生成的 .mcp.json 使用 npx，因此无论软件包是全局安装还是本地安装都能正常工作。

全局安装（npm install -g mcp-db-connect）

mcp-db-connect 位于 PATH 中，可直接使用：

claude mcp add --transport stdio db-connect --scope local -- mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "mcp-db-connect",
      "args": ["start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

本地安装（npm install --save-dev mcp-db-connect）

使用 npx，让 Claude Code 能在 node_modules/.bin 中找到可执行文件：

claude mcp add --transport stdio db-connect --scope local -- npx mcp-db-connect start --project . --config ./mcp-db.local.yml --env ./.env

.mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Codex CLI

推荐的自动设置方式：

mcp-db-connect setup --ai codex --db mssql,oracle,mongodb
npm --prefix .\.mcp-tools\db-connect install
codex

项目 .codex/config.toml：

[mcp_servers.db-connect]
command = '.\.mcp-tools\db-connect\node_modules\.bin\mcp-db-connect.cmd'
args = ["start", "--project", ".", "--config", '.\mcp-db.local.yml', "--env", '.\.env']
enabled = true

[mcp_servers.db-connect.env]
LOG_LEVEL = "silent"

向导创建的 .mcp-tools/db-connect/package.json 文件使用 npm 上的 mcp-db-connect。每个项目运行一次上面的安装命令即可。

Gemini CLI

推荐的自动设置方式：

mcp-db-connect setup --ai gemini --db mongodb
gemini

项目 .gemini/settings.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Kimi CLI

推荐的自动设置方式：

mcp-db-connect setup --ai kimi --db oracle
kimi --mcp-config-file .\.kimi\mcp.json

项目 .kimi/mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Kimi CLI 也可以使用 kimi mcp add 管理全局 MCP 服务，但上述项目本地文件可以将此数据库 MCP 的作用范围限定在一个项目中。

通用 MCP JSON

适用于接受常见 MCP JSON 格式的客户端：

mcp-db-connect setup --ai generic --db mssql

使用 .mcp-db-connect/mcp.json：

{
  "mcpServers": {
    "db-connect": {
      "command": "npx",
      "args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
      "env": {
        "LOG_LEVEL": "silent"
      }
    }
  }
}

Streamable HTTP 客户端

支持 Streamable HTTP 的 MCP 客户端或 Agent 可使用此端点：

http://127.0.0.1:3000/mcp

健康检查：

http://127.0.0.1:3000/healthz

配置

security:
  defaultMaxRows: 100
  queryTimeoutMs: 10000
  blockMultiStatement: true
  allowWriteOperations: false
  maskColumns:
    - password
    - token
    - secret
    - api_key
  auditLogPath: ./logs/mcp-db-connect.audit.jsonl

connections:
  mssql_report:
    type: mssql
    host: 172.27.62.7
    port: 1433
    database: Internet
    username: report_reader
    passwordEnv: MSSQL_REPORT_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mssql_write_model:
    type: mssql
    host: 172.27.62.8
    port: 1444
    database: InternetWrite
    username: writer_user
    passwordEnv: MSSQL_WRITE_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin
    mode: readonly

  mssql_local:
    type: mssql
    host: localhost
    port: 1433
    database: appdb
    username: sa
    passwordEnv: MSSQL_PASSWORD
    encrypt: true
    trustServerCertificate: true
    mode: readonly

  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    mode: readonly

  postgres_local:
    type: postgres
    host: localhost
    port: 5432
    database: appdb
    username: app_readonly
    passwordEnv: POSTGRES_PASSWORD
    mode: readonly

  mysql_local:
    type: mysql
    host: localhost
    port: 3306
    database: appdb
    username: app_readonly
    passwordEnv: MYSQL_PASSWORD
    mode: readonly

  qdrant_local:
    type: qdrant
    url: http://localhost:6333
    apiKeyEnv: QDRANT_API_KEY
    mode: readonly

  sqlite_local:
    type: sqlite
    file: ./data/appdb.sqlite
    mode: readonly

SQLite 没有主机、端口或用户名——file 是数据库文件的路径（相对路径以进程的工作目录为基准解析），也接受 :memory:，用于创建临时的进程内数据库。

MongoDB 会将所选端口保存在 .env 中的 URI 里，例如：

MONGODB_URI=mongodb://user:password@localhost:27018/appdb

Oracle Thin 模式与 Thick 模式

默认的 Oracle 配置使用 clientMode: thin，无需安装 Oracle Instant Client：

connections:
  oracle_local:
    type: oracle
    host: localhost
    port: 1521
    serviceName: ORCLPDB1
    username: app_readonly
    passwordEnv: ORACLE_PASSWORD
    clientMode: thin

无需安装 Oracle Instant Client。如果数据库包含 NCHAR/NVARCHAR2 列，且 NLS_NCHAR_CHARACTERSET = AL16UTF16，连接器会自动在服务端将查询改写为把这些列转换为 VARCHAR2，以便 Thin 模式处理。

使用连接字符串代替单独的字段

Oracle、MSSQL、PostgreSQL 和 MySQL/MariaDB 也接受原始连接字符串，以代替 host/port/database/username：

connections:
  mssql_from_string:
    type: mssql
    connectionStringEnv: MSSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

  oracle_from_string:
    type: oracle
    connectDescriptor: (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=10.20.30.15)(PORT=1521)))(CONNECT_DATA=(SERVER=POOLED)(SERVICE_NAME=DEMOPDB1)))
    username: demo_ora_user
    passwordEnv: ORACLE_FROM_STRING_PASSWORD
    mode: readonly

  postgres_from_string:
    type: postgres
    connectionStringEnv: POSTGRES_FROM_STRING_CONNECTION_STRING
    mode: readonly

  mysql_from_string:
    type: mysql
    connectionStringEnv: MYSQL_FROM_STRING_CONNECTION_STRING
    mode: readonly

connectionStringEnv 指向 .env 中的完整 ADO/tedious 连接字符串（MSSQL）、postgres://user:password@host:5432/database URI（PostgreSQL）或 mysql://user:password@host:3306/database URI（MySQL/MariaDB）（约定与 MongoDB 的 uriEnv 相同）。connectDescriptor 保存 Oracle TNS 连接描述符或 Easy Connect 字符串，不属于机密信息——只有密码需要放在 .env 中。设置向导会根据粘贴的连接字符串自动生成这些配置；也仍可使用上文所示的结构化 host/port/... 字段手动编写这两种配置。

PostgreSQL 和 MySQL/MariaDB 连接也接受 ssl: true（对于托管数据库提供商常见的自签名证书，可设置 rejectUnauthorized: false）。

通过环境变量配置

所有会加载配置的命令（start、serve-http、validate-config、test-connections）也接受将整个配置文档——即通常存储在 mcp-db.local.yml 中的同一套 security + connections 结构——以 YAML 或 JSON 格式放入 MCP_DB_CONFIG 环境变量，而不必使用文件：

export MCP_DB_CONFIG='
connections:
  postgres_demo:
    type: postgres
    host: db.example.com
    port: 5432
    database: appdb
    username: app_readonly
    password: change-me
    mode: readonly
'
mcp-db-connect serve-http --host 0.0.0.0 --port 3000

设置 MCP_DB_CONFIG 后，会完全跳过 --config/mcp-db.local.yml/mcp-db.yml/mcp-db.yaml 文件查找——无需存在任何配置文件。这样一来，无法将项目文件挂载到容器中的容器平台（Smithery.ai 及类似的托管 MCP 平台）也能运行此服务：它们会改为将整个配置注入为一个环境变量。机密信息可以直接写入（如上文中的 password:/connectionString:），也可以继续通过各自的环境变量间接引用（使用 passwordEnv/connectionStringEnv 等）——两种方式的行为都与使用文件时完全相同。

工具

SQL（Oracle + MSSQL + PostgreSQL + MySQL/MariaDB + SQLite）

• db_list_connections — 列出已配置的连接
• db_test_connection — 测试连接
• db_list_schemas — 列出架构
• db_list_tables — 列出表
• db_describe_table — 描述列（包括可用时的目录注释）、主键、外键和索引
• db_query — 运行只读 SQL 查询
• db_explain_query — 返回 SQL 查询的执行计划
• db_count — 统计表中的行数，可选用 WHERE 子句筛选

db_query 和 db_explain_query 接受可选的 params 数组，用于绑定参数。Oracle 和 PostgreSQL 使用位置绑定（Oracle 使用 :1、:2……；PostgreSQL 使用 $1、$2……）；MySQL/MariaDB 和 SQLite 按数组顺序使用 ? 占位符；MSSQL 没有位置语法，因此会按数组顺序将 params 绑定为命名参数 @p1、@p2……

SQLite 除 main（以及任何已附加的数据库）外没有架构/数据库的概念；db_list_schemas 通过 PRAGMA database_list 反映这一点，而 db_explain_query 运行的是 EXPLAIN QUERY PLAN，而不是基于成本的计划。

如果数据库为列设置了目录注释/描述，db_describe_table 会包含每列的注释/描述（Oracle 使用 all_col_comments，PostgreSQL 使用 COMMENT ON COLUMN，MySQL/MariaDB 使用 COLUMN_COMMENT，MSSQL 使用 MS_Description 扩展属性）——只有至少一列实际有注释时，输出中才会显示 comment 列。SQLite 没有注释机制，因此不会填充该字段。

MongoDB

• db_list_connections — 列出已配置的连接
• db_test_connection — 测试连接
• db_list_schemas — 列出数据库
• db_list_tables — 列出集合
• db_describe_table — 对集合字段进行采样
• db_mongo_find — 运行只读查找操作
• db_mongo_aggregate — 运行只读聚合管道
• db_mongo_count — 统计文档数，可选用筛选条件
• db_mongo_get_indexes — 列出集合的索引
• db_mongo_explain_find — 返回查找操作的执行计划
• db_mongo_explain_aggregate — 返回聚合管道的执行计划
• db_mongo_insert — 插入一个或多个文档
• db_mongo_update — 更新符合筛选条件的文档（many: true 表示更新所有匹配项，否则只更新第一个）
• db_mongo_delete — 删除符合筛选条件的文档（many: true 表示删除所有匹配项，否则只删除第一个）

除非连接配置了 mode: readwrite 且 security.allowWriteOperations: true，否则会阻止使用 db_mongo_insert/db_mongo_update/db_mongo_delete——这与 SQL 连接器对写入 SQL 语句的限制方式一致。db_mongo_update 和 db_mongo_delete 还要求 filter 非空，避免因误传 {} 而静默更新或删除整个集合。

db_describe_table 通过对文档进行采样来推断 MongoDB 列类型。默认采样数量为 20，可通过每个连接的 describeSampleSize 设置，也可通过工具的 sampleSize 参数在单次调用时覆盖：

connections:
  mongo_local:
    type: mongodb
    uriEnv: MONGODB_URI
    database: appdb
    describeSampleSize: 100
    mode: readonly

db_mongo_find 接受可选的 skip 参数，用于分页（跳过前 N 个匹配文档，然后以 maxRows 作为页面大小）。

Qdrant（向量搜索）

• db_list_connections — 列出已配置的连接
• db_test_connection — 测试连接
• db_list_tables — 列出集合
• db_describe_table — 描述集合的向量配置和负载字段类型
• db_qdrant_search — 执行向量相似性搜索，可选筛选条件和分数阈值
• db_qdrant_scroll — 浏览或筛选点，无需进行向量搜索
• db_qdrant_count — 统计点的数量，可选筛选条件

对于 Qdrant 连接，db_list_schemas 会返回空列表，因为 Qdrant 集合不会按架构／数据库分组。

db_qdrant_scroll 支持翻页浏览整个集合：当还有更多点时，每个响应都会包含一行 Next offset — 将该值作为 offset 参数传入下一次调用即可继续。省略 offset 则从头开始。

查询结果工具会返回如下表格：

Rows: 2

| id | name |
| --- | --- |
| 1 | Alice |
| 2 | Bob |

CLI 命令

• mcp-db-connect setup
• mcp-db-connect init
• mcp-db-connect ai-config
• mcp-db-connect validate-config
• mcp-db-connect test-connections
• mcp-db-connect start
• mcp-db-connect serve-http --host 127.0.0.1 --port 3000
• mcp-db-connect serve-http --api-key-env MCP_DB_HTTP_API_KEY
• mcp-db-connect update

更新

start 和 serve-http 每天会检查一次 npm 是否有更新版本（检查结果会缓存，且不会阻塞；离线时会静默跳过）；如果有可用版本，会向 stderr 打印通知 — 这绝不会影响 stdout，因此可安全用于 stdio 传输。检查范围仅限 ^<your current version>，即当前 0.x 次版本系列（例如，0.1.21 只会检查 0.1.22、0.1.23 等 — 不会检查 0.2.0）。该项目尚未达到 1.0.0，因此次版本号升级仍可能包含破坏性变更；缩小检查范围可避免静默升级到此类版本。

运行以下命令自行更新：

mcp-db-connect update              # checks and installs, if available
mcp-db-connect update --check-only # only checks, doesn't install
mcp-db-connect update --range "^0.2.0"  # override the range, e.g. to opt into a new minor line deliberately

该命令会检测软件包是全局安装的，还是作为本地项目依赖安装的，并运行相应的 npm install 命令。没有完全静默的后台自动安装 — 更新始终需要执行这条明确的命令（或者自行运行 npm install -g mcp-db-connect@latest / npm install --save-dev mcp-db-connect@latest）。

Docker

仓库根目录中的多阶段 Dockerfile 会将 CLI 构建为独立镜像。容器需要挂载项目的 mcp-db.local.yml 和 .env，因为连接配置通过文件提供，而非打包进镜像。

拉取已发布的镜像（每次发布时由 .github/workflows/release.yml 构建并推送到 GHCR）：

docker pull ghcr.io/phatngoit/mcp-db-connect:latest

或者在本地构建：

docker build -t mcp-db-connect .

通过 stdio 运行（适用于直接执行容器的 MCP 客户端），并挂载项目配置。将 mcp-db-connect 替换为 ghcr.io/phatngoit/mcp-db-connect:latest，即可使用已发布的镜像，而非本地构建的镜像：

docker run -i --rm \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect start --project /app/project

运行 Streamable HTTP 传输并发布端口：

docker run --rm -p 3000:3000 \
  -v "$(pwd)/mcp-db.local.yml:/app/project/mcp-db.local.yml:ro" \
  -v "$(pwd)/.env:/app/project/.env:ro" \
  mcp-db-connect serve-http --project /app/project --host 0.0.0.0 --port 3000

或者使用 examples/docker-compose.server.yml 示例，它会构建镜像，并从当前目录挂载 mcp-db.local.yml/.env：

docker compose -f examples/docker-compose.server.yml up --build

在云／容器平台上托管

如果设置了 MCP_DB_CONFIG，则无需挂载文件（请参阅通过环境变量配置）。当存在 PORT 环境变量时，镜像的入口点（docker-entrypoint.sh）也会自动从 stdio 切换为 Streamable HTTP 传输 — 这是 Smithery.ai、Railway、Render、Fly.io 等平台采用的惯例 — 并绑定到 0.0.0.0:$PORT，无需覆盖任何命令：

docker run -e PORT=8080 -e MCP_DB_CONFIG="$(cat mcp-db.local.yml)" -p 8080:8080 \
  ghcr.io/phatngoit/mcp-db-connect:latest

安全默认设置

该服务有意采用保守设置：

• 连接默认设为 readonly
• 除非全局配置和连接配置均允许写入，否则会阻止 SQL 写入和 DDL 关键字
• 会阻止执行多语句 SQL
• 除非全局配置和连接配置均允许写入，否则会阻止 MongoDB 聚合写入阶段以及 db_mongo_insert/db_mongo_update/db_mongo_delete
• db_mongo_update/db_mongo_delete 要求筛选条件非空，以免意外影响整个集合
• 结果行数受配置限制
• 会递归屏蔽敏感字段

请使用权限尽可能小的数据库账户。MCP 层是安全防护措施，不能替代数据库级权限。

注册目录

• Official MCP Registry — 通过仓库根目录中的 server.json，以 io.github.phatngoit/mcp-db-connect 的名称收录。发布工作流（.github/workflows/release.yml）会在每次 npm 发布后，通过 GitHub Actions OIDC 自动发布到此注册目录（无需存储令牌）。
• Glama.ai — 通过抓取此仓库建立索引；需手动提交，无需清单文件。
• Smithery.ai — 尚未提交。相关阻碍已解决：已提供 Dockerfile（发布至 ghcr.io/phatngoit/mcp-db-connect）、位于仓库根目录的 smithery.yaml 容器运行时清单、MCP_DB_CONFIG 环境变量配置（无需挂载文件），以及能够自动切换至 HTTP 传输的 PORT 感知入口点。提交仍需一次手动操作——通过 Smithery 的 GitHub App 在 smithery.ai/new 连接此仓库。由于编写时无法独立验证 smithery.yaml 的确切字段，提交前应先对照 Smithery 当前文档仔细核实。

路线图

• OpenTelemetry 跟踪
• 密钥管理器集成（AWS Secrets Manager、Azure Key Vault、HashiCorp Vault）