Dynamic DB MCP Server

把已有关系数据库通过简单配置变成安全的 MCP Server：API Key 授权、读/写控制、表级黑白名单、AST 级 SQL 校验、Key 有效期与限流/熔断、审计日志、Web 管理控制台。

📖 管理员操作手册见 docs/usage.md（功能使用说明）。

支持 PostgreSQL / MySQL / SQLite / SQL Server / Oracle，适配器接口化可继续扩展。

快速开始（开发模式）

1. 环境要求

• Node.js ≥ 20（推荐 24，内置 node:sqlite，项目零原生依赖）

• npm（随 Node 自带）

• 无需安装任何数据库——配置存储用内置 SQLite

2. 安装依赖

# 后端依赖（在根目录，后端依赖已合并进根 package.json）
npm install

# 前端依赖
npm --prefix web install

3. 启动

npm run dev          # 后端(8787) + 前端(Vite 3000) 一起启动
npm run dev -- --port 7100   # 指定前端端口（参数会转发给 Vite）

• 前端控制台：http://localhost:3000 （Vite 已配置 /api、/mcp 代理到后端）

• 后端 API：http://localhost:8787/api

4. 首次使用

1. 打开前端地址 → 引导页创建管理员账号（单管理员，密码 ≥ 6 位）

2. 系统已内置 SQLite 演示库 demo（只读，user_passwords 在黑名单），可直接体验

3. 「数据源」页添加真实数据库（PostgreSQL / MySQL / SQLite / SQL Server / Oracle），点「测试连接」确认

   • SQL Server：默认端口 1433；内网实例已默认 trustServerCertificate

   • Oracle：默认端口 1521，「数据库名」填服务名或 SID（如 ORCL、XEPDB1）；连接串可填 host:1521/服务名 或完整 connect descriptor；使用 oracledb Thin 模式，服务器无需安装 Oracle 客户端

4. 「API Keys」页创建密钥，勾选可访问数据源及读/写权限，按需设置有效期与限流/熔断（完整 Key 只显示一次）

5. 「MCP 接入」页复制端点与客户端配置片段，粘贴到 Cursor / Claude Desktop 等

6. 「模拟检验」页以 Key 视角验证有效表清单和 SQL 放行/拦截

7. 「审计日志」页查看全部调用流水（本地时间显示）

Related MCP server: MCP Databases Server

生产模式部署

生产模式下后端单进程托管一切：管理 API + MCP 端点 + 前端静态文件，只暴露一个端口（默认 8787）。

0. Docker 部署（最省心）

# 构建镜像（多阶段：前端构建 + 后端运行时，单容器全托管）
docker build -t dynamic-db-mcp-server .

# 运行（data 卷持久化配置/审计，首次启动在控制台创建管理员）
docker run -d --name dmcp -p 8787:8787 -v dmcp-data:/app/data dynamic-db-mcp-server

# 或 docker compose
docker compose up -d

访问 http://<服务器>:8787/。镜像基于 node:24-alpine，内置健康检查（/health）；自定义端口用 -e PORT=9000 -p 9000:9000。注意：容器内连接数据库时，主机地址不能用 localhost（指容器自身），请用数据库实际 IP；SQLite 数据源的文件路径需位于挂载进容器的目录中。

1. npm 包安装（免构建）

项目可作为单个 npm 包分发：包内已含预构建的前端控制台，安装方只需 Node.js ≥ 20，无需 clone 仓库、无需构建。

# 在仓库内打包（prepack 钩子会自动构建前端，产出 dynamic-db-mcp-server-x.y.z.tgz）
npm pack

# 目标机器安装（tgz 直接分发，或先 npm publish 到公网/私有 registry）
npm i -g ./dynamic-db-mcp-server-0.3.0.tgz
# 或：npm i -g dynamic-db-mcp-server

# 在任意目录启动；配置与审计数据落在当前目录 ./data（可用 DMCP_DATA_DIR 覆盖）
mkdir dmcp && cd dmcp
dynamic-db-mcp-server        # 或简写 dmcp；dmcp --port 9000 自定义端口（--host/--data-dir 见 dmcp --help）

也可以作为项目依赖安装后用 npx dynamic-db-mcp-server 启动，效果相同。

2. 源码构建与启动

# 安装依赖（后端只装生产依赖，在根目录）
npm install --omit=dev
npm --prefix web install

# 构建前端产物到 web/dist（后端会自动托管）
npm run build

# 启动生产服务
npm start
# 或自定义监听地址与端口
PORT=9000 HOST=0.0.0.0 npm start        # Linux/macOS
set PORT=9000 && npm start              # Windows cmd
$env:PORT=9000; npm start               # Windows PowerShell

启动后访问：

环境变量：

3. 数据与备份

• 所有配置（管理员、数据源、Key 哈希、审计日志）在 data/config.db，演示库在 data/demo.db

• 数据源密码落盘加密：config_json 中的 password / connectionString 以 AES-256-GCM 加密存储（enc:v1: 前缀），主密钥不入库——来自环境变量 DMCP_SECRET，或首次启动自动生成到 data/.secret（权限 600）。旧版本写入的明文会在启动时自动迁移为密文

• 备份 = 复制 data/ 目录（务必包含 data/.secret）；若主密钥通过 DMCP_SECRET 注入，则需单独妥善保管该值。丢失主密钥 = 所有数据源密码无法还原（其余数据不受影响）

• 数据库密码等敏感配置只存在服务端，API 返回一律脱敏（••••••••）；编辑数据源时不改密码则保留原密码

4. 进程常驻

Linux（systemd） /etc/systemd/system/dmcp.service：

[Unit]
Description=Dynamic DB MCP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/dynamic_mcp_server
Environment=PORT=8787 HOST=0.0.0.0
ExecStart=/usr/bin/node server/src/index.js
Restart=always
RestartSec=3
User=dmcp

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now dmcp

跨平台（pm2）：

npm install -g pm2
pm2 start server/src/index.js --name dmcp
pm2 save && pm2 startup     # 开机自启

Windows：推荐用 NSSM 注册为系统服务（GUI 操作）。

NSSM 安装为 Windows 服务：

1. 下载 NSSM（https://nssm.cc/download），解压后使用 win64\nssm.exe

2. 以管理员身份打开 cmd / PowerShell，执行：

nssm install DynamicMCPServer

3. 在弹出的图形界面中填写：

4. 点击 Install service 完成注册，然后启动：

nssm start DynamicMCPServer

验证：浏览器打开 http://<服务器>:8787/health 返回 {"ok":true,...} 即成功；后续可在「服务」（services.msc）中管理 DynamicMCPServer，卸载用 nssm remove DynamicMCPServer confirm。

注意：SQLite 数据源里的文件路径是服务器本机路径，服务默认以 LocalSystem 运行；如需访问网络共享盘上的库文件，在 NSSM 的 Log on 页签指定有权限的域/本机账号。

npm 全局安装的场景（npm i -g dynamic-db-mcp-server）：命令入口在 npm 全局前缀下，直接用 NSSM CLI 注册（无需 GUI）：

:: 1. 查 node 与 npm 全局前缀的实际路径
where.exe node
npm config get prefix

:: 2. 注册服务（路径按上一步输出替换；--port 等参数直接跟在入口脚本后）
nssm install DynamicDBMCPServer "C:\Program Files\nodejs\node.exe" "C:\Users\<你>\AppData\Roaming\npm\node_modules\dynamic-db-mcp-server\bin\dmcp.js" --port 8787

:: 3. 工作目录即数据根目录：服务启动后数据在 D:\apps\dmcp\data
nssm set DynamicDBMCPServer AppDirectory D:\apps\dmcp

:: 4. 可选：日志落盘 / 显式指定数据目录
nssm set DynamicDBMCPServer AppStdout D:\apps\dmcp\data\service.log
nssm set DynamicDBMCPServer AppStderr D:\apps\dmcp\data\service.log
nssm set DynamicDBMCPServer AppEnvironmentExtra DMCP_DATA_DIR=D:\dmcp-data

:: 5. 启动
nssm start DynamicDBMCPServer

提示：npm 全局前缀默认在安装用户的目录下（C:\Users\<你>\AppData\Roaming\npm），服务以 LocalSystem 运行通常也能读取；若希望路径与具体用户解耦，先执行 npm config set prefix D:\npm-global 再全局安装，入口路径相应变为 D:\npm-global\node_modules\dynamic-db-mcp-server\bin\dmcp.js。

5. 反向代理 + HTTPS（推荐）

MCP 客户端跨机访问时建议在前面挂 Nginx/Caddy 终止 TLS。注意 Streamable HTTP 需要关闭响应缓冲：

server {
    listen 443 ssl;
    server_name mcp.example.com;
    ssl_certificate     /etc/nginx/certs/mcp.pem;
    ssl_certificate_key /etc/nginx/certs/mcp.key;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;            # MCP/SSE 必需
        proxy_read_timeout 3600s;
    }
}

此时后端可只绑本机：HOST=127.0.0.1 npm start，MCP 客户端配置 https://mcp.example.com/mcp。

6. 客户端接入（生产）

{
  "mcpServers": {
    "dmcp-prod": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

不支持自定义 Header 的客户端用 URL 形式：https://mcp.example.com/mcp/key/<API_KEY>。

客户端连接后看到的工具按授权动态生成：<数据源slug>_list_tables / _describe_table / _query / _sample_rows，有写权限时另有 <数据源slug>_execute，外加全局 list_datasources。

7. 上线安全检查清单

• 修改初始管理员密码（侧栏底部「修改密码」）

• 每个客户端一个独立 API Key，最小化授权数据源与读/写

• 敏感表加入黑名单（如 *.user_passwords、sys.*）

• 生产数据源尽量用只读数据库账号连接（双保险）

• 跨机访问走 HTTPS 反代；仅本机使用设 HOST=127.0.0.1

• 定期备份 data/ 目录（含 .secret 主密钥文件）；审计日志可在控制台导出核查

• 生产环境用 DMCP_SECRET 显式管理加密主密钥，并将其纳入密钥管理/灾备流程

权限模型

• 数据源级：启用开关、只读/允许写、表白名单/黑名单（每条按正则整体匹配表名或 schema.table，如 orders、^order_.*$、^public\..*；单独的 * 表示全部；非合法正则按 * 通配的 glob 处理，如 *.user_passwords；黑名单优先）、行数上限、查询超时

• Key 级：逐数据源读/写授权；写工具需「Key 授权写」且「数据源允许写」双条件；支持有效期（到期自动失效）、每分钟限流与超限熔断（熔断期返回 429 + Retry-After，冷却自动恢复）、终端 IP 黑/白名单（* 通配，命中返回 403 并记审计）

• 异常预警：概览页自动识别多终端使用（24h ≥ 3 个不同 IP）、访问频率过高（1h ≥ 600 次）、熔断中的 Key，并给出控制建议

• SQL 校验：node-sql-parser AST 分类 + 表名提取；单语句限制；解析失败时写一律拒

验证

npm test    # 28 条端到端用例（setup/认证/MCP 全链路/权限拦截/审计/模拟器）

目录

dev.mjs             # 根 dev 启动器（转发 CLI 参数给 Vite）
bin/dmcp.js         # npm 包全局命令入口（dynamic-db-mcp-server / dmcp）
scripts/publish-readme.md  # npm 发布页专用简介（pack 时替换 README.md，由 scripts/pack-readme.mjs 驱动）
server/             # 后端：Express API + MCP 端点 + node:sqlite 配置存储
web/                # 前端：React + shadcn/ui 管理控制台
data/               # 运行时生成：config.db、demo.db
Dockerfile          # 多阶段一体化镜像（前端构建 + 后端单端口托管）
docker-compose.yml  # compose 编排（data 卷持久化）
docs/design.md      # 需求分析与设计方案（v0.2）
docs/usage.md       # 功能使用说明（管理员操作手册）

开源许可

本项目以 MIT License 开源：允许自由使用、复制、修改、分发（包括商用），须保留版权声明；软件按"现状"提供，不附带任何担保。