database-multi-mcp

database-multi-mcp：多数据库动态连接 MCP。连接信息由用户在运行时提供，不在项目配置里写死；支持 MySQL、PostgreSQL、ClickHouse、SQLite、DuckDB、MongoDB 直连，以及 DataSea、CloudBeaver/DBeaver Web 查询入口。按入口 profile 与库/连接别名保存、发现和复用；默认只读查询与 schema 探查，内存连接空闲 5 分钟断开，按简称查询为短连接。

推荐用法

在 Cursor 里启用 MCP 后，通常用自然语言描述目标即可，Agent 会按下面顺序调用工具：

1. 接入入口：user_db_test_connection 验证账号，再 user_db_connect 并传 alias 保存入口 profile。
2. 发现范围：首次连接返回的 discovery 会列出可选实例/连接/库；也可调用 user_db_discover_scopes。
3. 临时查询：未保存库别名前，用 user_db_*_query_database 或 user_db_query_scope 按 scope 查询。
4. 保存库别名：用户明确要求「起别名」时，调用 user_db_datasea_save_database_alias、user_db_cloudbeaver_save_connection_alias 或 user_db_save_scope_alias。
5. 日常查询：对已保存别名用 user_db_query_alias 短连接查询；大结果集提高 limit（上限见下文）。

示例对话

以下写法与常见使用过程一致（敏感信息请自行替换）：

添加 datasea，地址是 192.168.0.72/sql/query，账号是 <账号>，密码是 <密码>

现在有多少个库

查询 charging 库，起别名充电，查询 a_area 有多少数据

查询 customer_service 库，起别名客服，查询 cc_audio_file 有多少数据

查询 digital_portal 库，起别名 dg，查询 common_menu 有多少数据

添加 dbeaver，地址 http://clouddb.example.com/dbeaver/#/，账号 readonly，密码 <密码>

查出 kepg 的 capability_registry 表所有的数据

入口与库别名

• 入口 profile（profile_kind=entry）：平台账号或直连库账号，例如 datasea、dbeaver。
• 库别名（挂在入口的 targets）：具体实例/连接 + 数据库，例如 DataSea 的 充电 → charging。
• 直连库别名（profile_kind=target）：一次保存即含 host/port/database，例如 kepg（Postgres）、生产ck（ClickHouse）。

不同入口下可以有同名库别名（如 DataSea 与 DBeaver 都叫 充电）。user_db_query_alias 遇歧义会报错并给出候选项，用 入口别名/库别名 指定，例如 datasea/充电、dbeaver/充电。

profiles.json 中入口与 target 的关系示意：

{
  "profiles": [
    {
      "profile_name": "datasea",
      "alias": "datasea",
      "profile_kind": "entry",
      "backend": "datasea",
      "host": "http://192.168.0.72/sql/query",
      "username": "<账号>",
      "targets": [
        {
          "profile_name": "充电",
          "alias": "充电",
          "scope": {
            "instance": "徐州充电生产",
            "database": "charging"
          }
        }
      ]
    },
    {
      "profile_name": "kepg",
      "alias": "kepg",
      "profile_kind": "target",
      "backend": "postgres",
      "host": "172.16.255.77",
      "port": 31210,
      "database": "deerflow",
      "scope": { "database": "deerflow" }
    }
  ]
}

行为规则

• 默认不保存连接信息。
• user_db_test_connection 只测试连接，不累计次数。
• user_db_connect 成功后会按数据库指纹累计次数。
• user_db_connect 传 alias / 简称时，会立即保存为 profile，后续可按简称查询。
• 同一数据库成功连接次数 > 3 时，自动保存到 profiles.json。
• profiles.json 按用户要求明文保存密码；请勿提交到版本库，并限制本机文件权限。
• user_db_connect 创建的内存连接默认空闲 5 分钟后自动清理（可用 DATABASE_MULTI_MCP_IDLE_TIMEOUT_SECONDS 覆盖）。
• user_db_query_alias 使用短连接：按简称连接、查询、关闭，不会长期占用连接。若多个 entry profile 下存在同名 target alias，会返回候选项；可用 entry_profile/alias 精确指定，例如 datasea/充电 或 dbeaver/充电。
• DataSea / DBeaver Web 请求失败会最多尝试 3 次；仍失败时会提示检查网络、VPN 是否登录和内网地址是否可访问。
• 默认只支持只读 SQL：SELECT、WITH、SHOW、DESCRIBE、DESC、EXPLAIN、PRAGMA。MongoDB 使用 JSON 只读查询。
• 单次查询默认返回最多 100 行；limit 最大 10000。全表导出时先 SELECT COUNT(*)，再按需提高 limit 或分批查询。
• DataSea / DBeaver Web 单次保护上限为 2000 行。发现 SQL 未写 LIMIT 或请求大批量数据时会在结果里返回 warnings，提醒分批分页查询，但不会直接阻断只读查询。
• 支持将内部 Web SQL 平台作为后端：datasea 通过 HTTP API 登录和查询；cloudbeaver / dbeaver 通过 CloudBeaver GraphQL 登录和查询。Web 地址可以传裸 IP/域名，MCP 会自动补 http://；CloudBeaver 会尝试用户路径、/dbeaver 和站点根路径。
• 新 profile 会补充 profile_kind、backend、entry_profile、scope 等规范字段；旧 profile 继续兼容读取。

数据库指纹：

db_type + host + port + database + username

SQLite / DuckDB 使用：

db_type + path + username

按后端接入

DataSea

db_type=datasea
host=http://192.168.0.72/sql/query
username=<账号>
password=<密码>
alias=datasea

host 可传页面地址，MCP 会取 URL origin 并调用 /apiv1/api/v1/... 接口；如部署路径不同，可在 extra_json 中传 api_prefix 覆盖。

首次使用 DataSea 时，user_db_test_connection / user_db_connect 会在同一次返回的 discovery 字段里列出当前账号可选的 instance_name / database。用户确认后可调用 user_db_datasea_list_tables 选表并用 user_db_datasea_query_database 临时查询。只有用户明确要求保存时，才调用 user_db_datasea_save_database_alias 保存成 alias；alias 会挂在 DataSea 入口 profile 的 targets 下，保存后即可用 user_db_query_alias 直接查询，例如：

alias=充电
sql=SELECT COUNT(*) AS total FROM a_area

或指定入口：

alias=datasea/充电
sql=SELECT COUNT(*) AS total FROM a_area

CloudBeaver / DBeaver Web

db_type=cloudbeaver
host=http://clouddb.example.com/dbeaver/#/
username=readonly
password=<密码>
alias=dbeaver

首次使用 CloudBeaver / DBeaver Web 时，user_db_test_connection / user_db_connect 会在同一次返回的 discovery 字段里列出当前账号可选连接；如果只有一个连接，会继续列出该连接下的数据库。用户确认后可调用 user_db_cloudbeaver_list_tables 选表并用 user_db_cloudbeaver_query_database 临时查询。只有用户明确要求保存时，才调用 user_db_cloudbeaver_save_connection_alias 保存成 alias；alias 会挂在 CloudBeaver 入口 profile 的 targets 下，保存后即可用 user_db_query_alias 执行只读 SQL。

直连数据库（MySQL / Postgres / ClickHouse 等）

db_type=postgres
host=172.16.255.77
port=31210
database=deerflow
username=deerflow
password=<密码>
alias=kepg

保存后可直接：

alias=kepg
sql=SELECT * FROM capability_registry ORDER BY 1
limit=10000

ClickHouse、MySQL 等同理；user_db_connect 传 alias 后写入顶层 profile，不必再挂 targets。

MongoDB

db_type=mongodb
host=127.0.0.1
port=27017
database=<可选，入口 profile 可留空用于发现库>
username=<可选>
password=<可选>
extra_json={"auth_source":"admin"}

MongoDB 查询使用 JSON，只开放 find / count / aggregate，并禁止 $out / $merge：

{"collection":"users","filter":{"status":"active"},"projection":{"name":1},"limit":10}

统一发现流程

user_db_discover_scopes(profile_name)
user_db_discover_tables(profile_name, scope_json)
user_db_query_scope(profile_name, scope_json, sql, limit)
user_db_save_scope_alias(profile_name, scope_json, alias)

统一工具会尽量封装不同后端差异：DataSea 的 scope 是 instance + database，DBeaver 的 scope 是 project_id + connection_id + database，MySQL/Postgres/ClickHouse/MongoDB 通常是 database（Postgres 可额外带 schema）。user_db_save_scope_alias 不会在顶层复制一份带账号密码的 profile，而是把目标 alias 写入入口 profile 的 targets。不同入口下可以有相同 alias；查询或删除遇到重复 alias 时，会要求用户选择具体 entry_profile/alias。

文件

• server.py：MCP server 和工具实现。

运行时数据目录：

• macOS / Linux：~/.cursor/mcp-servers/database-multi-mcp/
• Windows：%APPDATA%\Cursor\database-multi-mcp\

该目录下会生成：

• profiles.json：自动保存的连接 profile，密码按用户要求明文保存。
• usage_counts.json：未达到自动保存阈值前的使用次数统计，不保存密码。

可通过环境变量 DATABASE_MULTI_MCP_DATA_DIR 覆盖数据目录。npm/npx 安装版默认也使用上述固定用户目录，避免 profile 落在可被清理的 npx 缓存目录。

工具

默认工具面为 compact，只暴露常用统一入口，减少 MCP tool schema 注入上下文的体积：

• user_db_connect：建立运行时连接，返回 connection_id；传 alias / 简称时立即保存 profile。
• user_db_query：按 connection_id 执行只读查询。
• user_db_query_alias：按已保存的 alias / 简称一键连接、查询并关闭连接。
• user_db_discover_scopes：统一列出某个 entry profile 下可选择的实例/连接/数据库范围。
• user_db_query_scope：统一按用户选择的 scope 临时查询，不保存 profile。
• user_db_profile：统一管理 profile，action 支持 list、delete、save_scope_alias。

如需恢复旧版完整工具面，可设置环境变量 DATABASE_MULTI_MCP_TOOL_SURFACE=full（legacy / all 同义）。完整工具面会额外注册：

• user_db_test_connection：测试用户提供的连接信息。
• user_db_connect_profile：使用已保存 profile 连接。
• user_db_discover_tables：统一按用户选择的 scope 临时列表，不保存 profile。
• user_db_save_scope_alias：统一把用户明确选择的 scope 保存为 alias。
• user_db_datasea_list_databases：列出 DataSea 可用实例和数据库，供首次选择。
• user_db_datasea_list_tables：按用户选择的 DataSea 实例和数据库临时列表，不保存 profile。
• user_db_datasea_query_database：按用户选择的 DataSea 实例和数据库临时查询，不保存 profile。
• user_db_datasea_save_database_alias：把选中的 DataSea 实例/数据库保存为 alias。
• user_db_cloudbeaver_list_connections：列出 CloudBeaver / DBeaver Web 可用连接，供首次选择。
• user_db_cloudbeaver_list_databases：列出 CloudBeaver / DBeaver Web 连接下的数据库。
• user_db_cloudbeaver_list_tables：按用户选择的 CloudBeaver / DBeaver Web 连接和数据库临时列表，不保存 profile。
• user_db_cloudbeaver_query_database：按用户选择的 CloudBeaver / DBeaver Web 连接和数据库临时查询，不保存 profile。
• user_db_cloudbeaver_save_connection_alias：把选中的 CloudBeaver / DBeaver Web 连接/数据库保存为 alias。
• user_db_list_tables：列出表。
• user_db_describe_table：查看表结构。
• user_db_disconnect：关闭由 user_db_connect 创建的运行时连接。
• user_db_list_profiles：查看已保存 profile。
• user_db_delete_profile：删除已保存 profile。
• user_db_list_connections：查看当前 MCP 进程内连接。
• user_db_cleanup_idle_connections：主动清理空闲连接。

Cursor MCP 配置

npx 方式

发布到 npm 后，可在 Cursor MCP 配置中使用：

{
  "mcpServers": {
    "database-multi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "database-multi-mcp"
      ]
    }
  }
}

npm 包装层会调用 uv run python server.py 启动 Python MCP，因此运行机器需要安装 uv。如 uv 不在 PATH，可设置环境变量 DATABASE_MULTI_MCP_UV_COMMAND 指向 uv 可执行文件。

本地开发方式

/Users/jarker/.cursor/mcp.json 中配置：

{
  "mcpServers": {
    "database-multi-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jarker/.cursor/mcp-servers/database-multi-mcp",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}