DB MCP Server

English | 中文

一个基于 TypeScript 实现的 Model Context Protocol 服务，让 Claude Code 可以直接查询 Oracle、PostgreSQL 和 MySQL 数据库。

支持的数据库

• Oracle（通过 oracledb 驱动，默认 thin 模式）
• PostgreSQL（通过 pg 驱动）
• MySQL（通过 mysql2 驱动）

提供的工具

• list_tables：列出指定 schema / 数据库下的表
• describe_table：查看表结构、字段类型和约束
• execute_query：执行只读的 SELECT 查询
• execute_dml：执行 INSERT/UPDATE/DELETE/DDL 语句
• add_data_source：运行时动态连接新数据库，无需重启
• list_data_sources：列出所有已连接的数据源

每个工具都支持可选参数 dataSource（数据源名称，见 list_data_sources）。如果只连接了一种数据库，会默认使用该数据库。

动态添加数据源

数据分散在多个库时，不用改配置重启，直接让 Claude 调用 add_data_source：

add_data_source(name="mysql-report", type="mysql", host="192.168.1.10",
                port=3306, user="reader", password="***", database="report")

连接成功后即可通过 dataSource="mysql-report" 在其他所有工具中使用。 注意：通过工具传入的凭据会出现在会话日志中，长期固定的数据源建议仍用环境变量配置。

环境要求

• Node.js 20+
• 至少配置一个数据库的环境变量

用户安装（推荐，无需克隆/编译）

前提：Windows + Node.js 20+。打开 PowerShell 执行一条命令：

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://cdn.jsdelivr.net/gh/HW-public/db-mcp-server@main/install.ps1'))"

脚本会自动：下载最新 Release 的单文件产物到 %USERPROFILE%\db-mcp-server\ → 生成 .env 配置模板 → 注册 .mcp.json → 启用 settings.local.json。

然后编辑 %USERPROFILE%\db-mcp-server\.env 填入数据库凭据，重启 Claude Code 即可。

网络无法访问 jsDelivr 时，把脚本地址换成 https://raw.githubusercontent.com/HW-public/db-mcp-server/main/install.ps1 再试。

安装（开发者）

方式一：一键安装（本地仓库）

在项目目录执行一次：

cd C:\Users\ASUS\db-mcp-server
pnpm install
pnpm run bundle
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

脚本会自动完成：

1. 把单文件产物 dist/bundle/index.mjs 拷贝到 release\（默认，可用 -InstallDir 指定其他目录）
2. 把项目里真实的 .env（没有则用 .env.example 模板）复制为 release\.env
3. 注册/更新 C:\Users\ASUS\.mcp.json 中的 db-mcp-server（原文件备份为 .mcp.json.bak）
4. 在 settings.local.json 中启用该服务器

之后升级只需重跑 pnpm run bundle + install.ps1。换机器只需拷贝 release\ 文件夹（内含 index.mjs + .env），手动把 .mcp.json 里路径指向新位置即可——运行时仅依赖 Node.js，无需 node_modules。

单文件产物仅支持 Oracle thin 模式；thick 模式需要 oracledb 原生客户端，请用方式二运行。

方式二：常规安装（开发/调试）

本项目强制使用 pnpm 管理依赖。

cd C:\Users\ASUS\db-mcp-server
pnpm install
pnpm run build

如果你用 npm install 或 yarn install，preinstall 脚本会报错并阻止安装。

配置

1. 环境变量 / .env 文件

支持两种配置方式，优先级如下：

1. 系统环境变量（最高优先级）
2. 项目根目录下的 `.env` 文件

示例 .env：

# Oracle 配置
ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
ORACLE_DSN=localhost:1521/ORCLPDB1

# PostgreSQL 配置
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=your_db

# MySQL 配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_user
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_db

也可以在启动 Claude Code 前用 PowerShell 设置：

$env:ORACLE_USER = "your_user"
$env:ORACLE_PASSWORD = "your_password"
$env:ORACLE_DSN = "localhost:1521/ORCLPDB1"

$env:POSTGRES_HOST = "localhost"
$env:POSTGRES_PORT = "5432"
$env:POSTGRES_USER = "your_user"
$env:POSTGRES_PASSWORD = "your_password"
$env:POSTGRES_DATABASE = "your_db"

$env:MYSQL_HOST = "localhost"
$env:MYSQL_PORT = "3306"
$env:MYSQL_USER = "your_user"
$env:MYSQL_PASSWORD = "your_password"
$env:MYSQL_DATABASE = "your_db"

claude

2. 在 Claude Code 中注册 MCP Server

使用一键安装（方式一）时此步已由脚本自动完成。手动注册时，在 C:\Users\ASUS\.mcp.json 中添加（直接用 node 启动，不再经过 cmd 包装，避免转义问题）：

{
  "mcpServers": {
    "db-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\ASUS\\db-mcp-server\\release\\index.mjs"]
    }
  }
}

.env 会按安装目录的绝对路径自动加载（从脚本所在目录向上查找），与启动目录无关。

在 C:\Users\ASUS\.claude\settings.local.json 中启用：

{
  "enabledMcpjsonServers": [
    "db-mcp-server"
  ]
}

修改环境变量、.mcp.json 或重新构建后，请重启 Claude Code 使配置生效。

构建与运行

pnpm run build
node dist/index.js

开发调试

无需编译，直接使用 tsx 运行：

pnpm tsx src/index.ts

Oracle Thick 模式

如果数据库需要使用 thick 模式，请设置：

$env:ORACLE_THICK_MODE = "1"
$env:ORACLE_LIB_DIR = "C:\Users\ASUS\Desktop\instantclient_19_28"

验证

重启 Claude Code 后，可以尝试：

• "列出 Oracle 的表"
• "列出 PostgreSQL 的表"
• "列出 MySQL 的表"
• "描述 postgres 中的 users 表"
• "描述 mysql 中的 users 表"
• "在 oracle 上执行 SELECT * FROM employees"
• "在 mysql 上执行 SELECT * FROM users"
• "列出所有已连接的数据源"
• "连接一个新的 MySQL 库 192.168.1.10:3306，命名为 mysql-report"