内容
# MCP DB 连接
[](https://www.npmjs.com/package/mcp-db-connect)
[](https://github.com/phatngoit/MCP-DB/actions/workflows/ci.yml)
适用于只读访问 Oracle 数据库、Microsoft SQL Server 和 MongoDB 的通用 MCP 服务器。
该项目旨在支持 Model Context Protocol 的 AI 工具。项目可以安装它，提供 YAML 配置文件，并为 AI 客户端公开安全的数据库工具。
Oracle 连接默认使用 Node.js `oracledb` 薄模式，因此大多数数据库不需要 Oracle Instant Client。某些 Oracle 数据库使用 Thin 模式无法处理的 NCHAR 字符集；这些数据库需要使用 Oracle Client 库的 Oracle Thick 模式。
默认情况下，从项目目录运行的命令会自动使用：
- `mcp-db.local.yml`，然后 `mcp-db.yml`，然后 `mcp-db.yaml`
- `.env`
## 功能
- Oracle、MSSQL 和 MongoDB 连接器
- 一个配置文件中的多个命名连接
- 默认只读
- SQL 多语句阻止
- 只读模式下阻止 MongoDB `$out` 和 `$merge`
- 行限制和查询超时
- 查询结果的 Markdown 表格输出
- 架构/表允许列表和拒绝列表
- 敏感字段屏蔽
- JSONL 审计日志
- AI 客户端和数据库连接的交互式设置向导
- 用于设置、初始化、验证、连接测试和 stdio/HTTP 服务器启动的 CLI
## 安装
**1. 安装包**
Node / TypeScript 项目（本地安装）：
```bash
npm install --save-dev mcp-db-connect
```
.NET、Python 或其他非 Node 项目（全局安装）：
```bash
npm install -g mcp-db-connect
```
**2. 运行设置向导**
```bash
npx mcp-db-connect setup
```
向导会询问要配置的 AI 客户端和数据库，提示连接详细信息，并自动编写所有配置文件。
**3. 测试连接**
```bash
npx mcp-db-connect test-connections
```
就这样 - 您的 AI 客户端现在已连接到您的数据库。
### 向导创建的内容
```text
mcp-db.local.yml # 数据库连接配置
.env # 本地密钥
.gitignore # 将密钥和本地配置排除在 git 之外
.mcp.json # Claude Code MCP 配置（如果选择）
.codex/config.toml # Codex CLI 配置（如果选择）
.gemini/settings.json # Gemini CLI 配置（如果选择）
.kimi/mcp.json # Kimi CLI 配置（如果选择）
```
### 其他设置选项
跳过具有显式标志的向导：
```bash
npx mcp-db-connect setup --ai claude,codex --db mssql,mongodb
```
覆盖现有的配置项：
```bash
npx mcp-db-connect setup --force
```
启动 HTTP MCP 端点而不是 stdio：
```bash
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
推荐的自动设置：
```bash
mcp-db-connect setup --ai claude --db mssql
```
生成的 `.mcp.json` 使用 `npx`，因此无论包是全局安装还是本地安装，都可以使用：
```json
{
"mcpServers": {
"db-connect": {
"command": "mcp-db-connect",
"args": ["start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
"env": {
"LOG_LEVEL": "silent"
}
}
}
}
```
### Codex CLI
推荐的自动设置：
```bash
mcp-db-connect setup --ai codex --db mssql,oracle,mongodb
npm --prefix .\.mcp-tools\db-connect install
codex
```
项目 `.codex/config.toml`:
```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
推荐的自动设置：
```bash
mcp-db-connect setup --ai gemini --db mongodb
gemini
```
项目 `.gemini/settings.json`:
```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
推荐的自动设置：
```bash
mcp-db-connect setup --ai kimi --db oracle
kimi --mcp-config-file .\.kimi\mcp.json
```
项目 `.kimi/mcp.json`:
```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 服务器，使用 `kimi mcp add`，但上面的项目本地文件将此数据库 MCP 限定在一个项目中。
### 通用 MCP JSON
对于接受通用 MCP JSON 格式的客户端：
```bash
mcp-db-connect setup --ai generic --db mssql
```
使用 `.mcp-db-connect/mcp.json`:
```json
{
"mcpServers": {
"db-connect": {
"command": "npx",
"args": ["mcp-db-connect", "start", "--project", ".", "--config", "./mcp-db.local.yml", "--env", "./.env"],
"env": {
"LOG_LEVEL": "silent"
}
}
}
}
```
## 可流式 HTTP 客户端
为支持可流式 HTTP 的 MCP 客户端或代理使用此端点：
```text
http://127.0.0.1:3000/mcp
```
健康检查：
```text
http://127.0.0.1:3000/healthz
```
## 配置
```yaml
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
```
MongoDB 将选定的端口存储在 `.env` 中保存的 URI 中，例如：
```dotenv
MONGODB_URI=mongodb://user:password@localhost:27018/appdb
```
### Oracle 薄模式 vs 厚模式
默认 Oracle 设置使用 `clientMode: thin`，不需要 Oracle Instant Client：
```yaml
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` 以便在服务器端处理。
## 工具
### SQL（Oracle + MSSQL）
- `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 子句
### 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` — 返回聚合管道的执行计划
查询结果工具返回表格，如下所示：
```text
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`
## 安全默认值
服务器故意保守：
- 连接默认为 `readonly`
- 除非全局和连接配置允许写入，否则阻止 SQL 写入和 DDL 关键字
- 阻止 SQL 多语句执行
- 阻止 MongoDB 聚合写入阶段
- 结果行数受配置限制
- 递归屏蔽敏感字段
使用具有尽可能小的权限的数据库帐户。MCP 层是一道防护栏，而不是数据库级权限的替代品。
## 路线图
- PostgreSQL 连接器
- MySQL / MariaDB 连接器
- MongoDB `db_describe_table` 的可配置样本大小（目前为 20 个文档）
- OpenTelemetry 跟踪
- 机密管理器集成（AWS Secrets Manager、Azure Key Vault、HashiCorp Vault）
