数据库助手 MCP 服务

这是给 Claude Code 使用的本地数据库 MCP 服务。产品和 MCP 身份是通用的 database-mcp-server / database-mcp，当前首个适配器使用 MySQL 驱动；以后可以在不改变工具契约的前提下增加其他数据库适配器。

服务通过 stdio 工作，连接地址、数据库名、用户名和密码由用户目录中的 JSON 配置文件提供。默认文件是：

Windows: %USERPROFILE%\database-mcp-server\config\settings.json
macOS/Linux: $HOME/database-mcp-server/config/settings.json

也可以通过 DATABASE_CONFIG_PATH 指定绝对路径。只有这个路径变量会从 MCP 启动环境读取，连接凭据不放在命令行参数中。

工具

典型的数据助手流程是先调用 database_config_status 或 database_environment_list，确认环境后调用 database_ping，再调用 database_list_tables 和 database_describe_table，最后使用参数化的 database_query。没有设置默认环境时，每个数据库工具都要传 environment。

Related MCP server: MySQL MCP Server

配置

把 config/settings.example.json 复制到默认路径后填写连接信息。多环境配置的每个键都是一个环境名；defaultEnvironment 是可选的，只是省略 environment 参数时的回退。最小配置如下：

{
  "schemaVersion": 1,
  "adapter": "mysql",
  "defaultEnvironment": "dev",
  "environments": {
    "dev": {
      "connection": {
        "host": "127.0.0.1",
        "port": 3306,
        "database": "业务库_dev",
        "user": "claude_reader",
        "password": "请填写密码"
      },
      "permissions": {
        "allowWrite": false,
        "allowDdl": false,
        "allowDestructive": false
      }
    },
    "prod": {
      "connection": {
        "host": "prod-db.example.com",
        "port": 3306,
        "database": "业务库_prod",
        "user": "claude_reader_prod",
        "password": "请填写密码"
      }
    }
  }
}

环境名只允许 Unicode 字母或数字开头，后续使用字母、数字、.、_ 和 -，长度为 1–64 个字符。每个环境都有独立的 connection，因此可以分别配置地址、端口、数据库、用户名、密码和 TLS；permissions、runtime 可以写在环境内，也可以在顶层作为所有环境的默认值。建议生产环境单独使用最小权限账号，并且不要把生产环境设置成默认环境。

在多环境配置中如果没有 defaultEnvironment，服务不会猜测要连接哪个环境。调用时显式传入环境：

{
  "environment": "staging",
  "sql": "SELECT COUNT(*) AS total FROM orders"
}

可以调用 database_environment_set_default({"environment":"dev"}) 设置回退环境，也可以在 database_configure 中传 environment 和 setAsDefault: true。调用 database_configure({"defaultEnvironment":null}) 可以移除回退。设置默认环境不会改变或记录一个“当前环境”；每次调用仍可传入其他环境。

旧版只有一个 connection 的配置文件仍然有效，服务会把它视为单一的 default 环境。只有在使用多环境配置时，才需要显式管理默认环境。 从旧配置向新环境迁移时，原连接会保留为 default，新环境单独写入；确认新环境可用后可以通过 database_environment_set_default 指定回退环境。

用户名和密码可以并列保存在这个用户目录中的 settings.json，这是为方便 Claude Code 读取而做的明确取舍。该文件等同于明文凭据：只允许当前操作系统用户读取，不能复制到 Git、压缩包、日志、截图或 Claude Code 的共享配置中。服务的状态、错误和工具响应都会省略密码；配置文件本身仍需要用户负责保护。

可选连接项包括 socketPath、charset、timezone 和 TLS；在多环境文件中把它们放到对应环境内：

{
  "environments": {
    "prod": {
      "connection": {
        "ssl": {
          "mode": "verify_identity",
          "caFile": "ca.pem",
          "certFile": "client-cert.pem",
          "keyFile": "client-key.pem"
        }
      },
      "runtime": {
        "connectionLimit": 4,
        "connectTimeoutMs": 10000,
        "queryTimeoutMs": 30000
      }
    }
  }
}

证书文件的相对路径以 settings.json 所在目录为基准。verify_ca 和 verify_identity 需要 CA 文件；生产环境建议使用 verify_identity。

也可以让 Claude Code 调用 database_configure 写入配置。例如只提交连接字段时，已经存在的密码会被保留：

{
  "environment": "staging",
  "host": "db.example",
  "port": 3306,
  "database": "sales",
  "user": "claude_reader",
  "password": "由用户填写"
}

上面的调用只更新 staging 环境，不会覆盖 dev 或 prod。如果要同时设为默认环境，再增加 "setAsDefault": true。完整的 environments 对象也可以通过 settings 或 config 一次提交。

接入 Claude Code

项目中的 claude-code.mcp.example.json 可作为 stdio 注册模板：

{
  "mcpServers": {
    "database-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/database-mcp-server/src/index.js"],
      "env": {
        "DATABASE_CONFIG_PATH": "/absolute/path/database-mcp-server/config/settings.json"
      }
    }
  }
}

如果 Claude Code 找不到 node，把 command 换成本机 Node.js 的绝对路径。启动后先调用 database_config_status 或 database_environment_list；编辑配置后调用 database_config_reload，不必重启 Claude Code。数据工具的 environment 参数优先于 defaultEnvironment。

SQL 行为与权限

服务允许多语句请求，会把 SQL 函数交给 MySQL 处理，UPDATE 和 DELETE 可以不带 WHERE，结果不会按行数或结果字节数截断。database_query 仍只接受 SELECT、SHOW、DESCRIBE、EXPLAIN 和读形式 WITH，并拒绝锁定读取、可执行注释和服务端文件导出；database_execute 拒绝账号/服务器/数据库级管理语句以及服务端文件导入导出。这些边界与多语句、函数、无 WHERE 和完整结果集是不同的策略。

DML、DDL 和破坏性 DDL 默认关闭：

{
  "permissions": {
    "allowWrite": false,
    "allowDdl": false,
    "allowDestructive": false
  }
}

需要写入时，先让 Claude Code 展示 SQL 和影响范围，再在调用 database_execute 时传 confirm: true，并按需打开对应开关。多语句写入遵循 MySQL 自动提交行为，后续语句失败时，前面已经成功的语句可能已经提交；服务不提供跨调用事务。

建议为 Claude Code 创建权限最小的 MySQL 账号。只读场景授予目标库的 SELECT、SHOW VIEW；写入场景再单独授予必要的 DML 权限。

安装与检查

开发机需要 Node.js 18.18 或更高版本：

pnpm install --prod
pnpm run check
pnpm test

Windows 公开制品不要求目标机安装 Node.js、npm、pnpm、npx、Docker 或联网下载；构建脚本会把 Node 运行时和生产依赖放进 ZIP。请先把 ZIP 完整解压到一个普通目录，再运行 START-HERE.html 或 INSTALL.cmd，不要直接从压缩包预览窗口启动。然后运行 CONFIGURE.cmd 从模板创建 %USERPROFILE%\database-mcp-server\config\settings.json；升级会保留配置，卸载默认也保留配置。

如果双击 INSTALL.cmd 失败，窗口会保留并显示 PowerShell 的原始错误；日志目录可写时，完整输出还会保存到 %USERPROFILE%\database-mcp-server\logs\install.log。日志目录不可写时，入口会直接显示输出，不会因为记录日志失败而跳过安装。请把该文件（或窗口）中的错误原文和 Get-ExecutionPolicy -List 输出交给管理员或维护者，不要只提供“错误码”。

真实 Windows x64 验收需要在干净 Windows + PowerShell 5.1 上完成；本仓库提供构建和清单脚本，但 macOS/Linux 本地检查不能替代该验收。

在 Windows 构建机上准备好官方 Windows x64 Node 运行时目录或 ZIP 后，可执行：

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-windows.ps1 `
  -NodeRuntime C:\path\to\node-v22.x-win-x64.zip
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\verify-windows-release.ps1 `
  -ZipPath .\dist\database-mcp-server-0.2.0-windows-x64.zip

如果能提供运行时来源，还可以把官方归档地址和 SHA-256 写入清单：

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-windows.ps1 `
  -NodeRuntime C:\releases\node-v22.14.0-win-x64.zip `
  -NodeRuntimeSourceUrl https://nodejs.org/dist/v22.14.0/node-v22.14.0-win-x64.zip `
  -NodeRuntimeArchiveSha256 <官方归档 SHA-256>

构建默认生成 CANDIDATE_UNVERIFIED 清单；只有把干净 Windows x64 + PowerShell 5.1 的安装、升级/回滚、配置重载和卸载证据传给构建脚本，才允许标记 VERIFIED。目标机永远不执行包管理器或在线下载。

INSTALL.cmd 会为单个 PowerShell 子进程使用 -ExecutionPolicy Bypass，不会修改用户或计算机的持久执行策略。如果组织通过 MachinePolicy 或 UserPolicy 禁止脚本，运行入口仍可能在脚本正文之前被拦截；此时在 PowerShell 中执行 Get-ExecutionPolicy -List，把输出和错误原文交给管理员，由管理员批准签名脚本或调整组织策略。不要为了安装而执行 Set-ExecutionPolicy 修改全局策略。