# DB MCP Server

[English](README.EN.md) | 中文

一个基于 TypeScript 实现的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务，让 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
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` 再试。

## 安装（开发者）

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

在项目目录执行一次：

```powershell
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](https://pnpm.io/) 管理依赖。

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

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

## 配置

### 1. 环境变量 / `.env` 文件

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

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

示例 `.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 设置：

```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 包装，避免转义问题）：

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

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

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

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

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

## 构建与运行

```powershell
pnpm run build
node dist/index.js
```

## 开发调试

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

```powershell
pnpm tsx src/index.ts
```

## Oracle Thick 模式

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

```powershell
$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"