npm package: @hyqf98/easy_db_mcp_server
Description: MCP server for database access (MySQL, PostgreSQL, SQLite)
Latest version: 3.0.0

# EasyDB MCP Server

一个通过 npx 部署的 MCP 服务器，为 AI 助手提供统一的数据库访问接口。

## 版本

v3.0.0 - 支持动态连接管理，17 个数据库操作工具

## 支持的数据库

- MySQL (5.7+)
- PostgreSQL (12+)
- SQLite (3+)

## 快速开始

```bash
npx hyqf98@easy_db_mcp_server
```

## 配置

### 环境变量

| 变量 | 必填 | 说明 |
|-----|-----|------|
| `EASYDB_TYPE` | 否 | 数据库类型：`mysql`、`postgresql` 或 `sqlite`（不设置时需使用 create_connection 工具创建连接） |
| `EASYDB_HOST` | 否 | 数据库主机（MySQL/PostgreSQL 连接时需要） |
| `EASYDB_PORT` | 否 | 数据库端口（默认值：MySQL=3306、PostgreSQL=5432） |
| `EASYDB_USER` | 否 | 数据库用户（MySQL/PostgreSQL 连接时需要） |
| `EASYDB_PASSWORD` | 否 | 数据库密码（MySQL/PostgreSQL 连接时需要） |
| `EASYDB_DATABASE` | 否 | 默认数据库名或 SQLite 文件路径 |
| `EASYDB_ALLOW_WRITE` | 否 | 已弃用（v3.0+ 动态连接始终允许写入） |
| `EASYDB_ALLOW_DDL` | 否 | 已弃用（v3.0+ 动态连接始终允许 DDL） |

### 配置示例

**MySQL：**
```bash
export EASYDB_TYPE=mysql
export EASYDB_HOST=localhost
export EASYDB_USER=root
export EASYDB_PASSWORD=secret
export EASYDB_DATABASE=mydb
```

**PostgreSQL：**
```bash
export EASYDB_TYPE=postgresql
export EASYDB_HOST=localhost
export EASYDB_USER=postgres
export EASYDB_PASSWORD=secret
export EASYDB_DATABASE=mydb
```

**SQLite：**
```bash
export EASYDB_TYPE=sqlite
export EASYDB_DATABASE=/path/to/database.db
```

## Claude Desktop 配置

将以下配置添加到 Claude Desktop 配置文件中：

**macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows：** `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@hyqf98/easy_db_mcp_server"],
      "env": {
        "EASYDB_TYPE": "mysql",
        "EASYDB_HOST": "localhost",
        "EASYDB_USER": "root",
        "EASYDB_PASSWORD": "your_password",
        "EASYDB_DATABASE": "mydb"
      }
    }
  }
}
```

## Claude Code

```cmd
claude mcp add --scope user --transport stdio easy_db_mcp_server --env EASYDB_TYPE=mysql --env EASYDB_HOST=host --env EASYDB_USER=root --env EASYDB_PASSWORD=123456 -- npx -y @hyqf98/easy_db_mcp_server
```

## 可用工具

### 连接管理工具 (v3.0.0 新增)

#### create_connection
创建新的数据库连接。

**参数：**
- `type`（必填）：数据库类型（`mysql`、`postgresql` 或 `sqlite`）
- `host`（必填*）：数据库主机（MySQL/PostgreSQL 必填）
- `port`（可选）：端口号（默认值：MySQL=3306、PostgreSQL=5432）
- `user`（必填*）：用户名（MySQL/PostgreSQL 必填）
- `password`（必填*）：密码（MySQL/PostgreSQL 必填）
- `database`（必填）：数据库名或 SQLite 文件路径
- `key`（可选）：自定义连接 key

**返回：**
```json
{
  "success": true,
  "key": "mysql-prod",
  "message": "Connection created successfully"
}
```

#### list_connections
列出所有已创建的数据库连接。

**参数：** 无

**返回：**
```json
{
  "connections": [
    {
      "key": "mysql-prod",
      "type": "mysql",
      "host": "localhost",
      "database": "production",
      "createdAt": "2026-02-05T10:00:00Z"
    }
  ],
  "count": 1
}
```

#### close_connection
关闭指定的数据库连接。

**参数：**
- `key`（必填）：要关闭的连接 key

#### close_all_connections
关闭所有数据库连接。

**参数：** 无

### 基础操作

#### list_tables
列出数据库中的所有表。

**参数：**
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**示例：**
```
请显示数据库中的所有表
```

#### describe_table
获取表的结构，包括列、类型和约束。

**参数：**
- `table`（必填）：表名
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**示例：**
```
显示 users 表的结构
```

#### execute_query
执行 SELECT 查询（只读）。

**参数：**
- `sql`（必填）：SQL SELECT 查询语句
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**示例：**
```
查找过去 7 天内创建的所有用户
```

#### execute_sql
执行任意 SQL 语句。

**参数：**
- `sql`（必填）：SQL 语句
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

### 批量操作（v2.0.0 新增）

#### execute_transaction
执行一组 SQL 语句作为事务，失败时自动回滚。

**参数：**
- `sql`（必填）：SQL 语句数组
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**示例：**
```
在事务中插入用户和关联的配置数据
```

#### batch_insert
批量插入数据，支持多行一次性插入。

**参数：**
- `table`（必填）：表名
- `data`（必填）：数据行数组
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `insertedRows`：成功插入的行数
- `duplicateRows`：重复的行数

**示例：**
```
批量插入 100 条用户数据
```

#### batch_update
批量更新数据，基于条件更新。

**参数：**
- `table`（必填）：表名
- `updates`（必填）：
  - `set`：要更新的列值
  - `where`：WHERE 条件
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `affectedRows`：受影响的行数

**示例：**
```
将所有状态为 inactive 的用户更新为 active
```

### 数据管理（v2.0.0 新增）

#### export_data
导出数据为 JSON/CSV 并保存到文件。

**参数：**
- `table`（必填）：表名
- `format`（必填）：导出格式（`json` 或 `csv`）
- `filePath`（可选）：文件保存路径（默认：`~/table_name.json`）
- `limit`（可选）：行数限制
- `where`（可选）：WHERE 条件
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `success`：是否成功
- `filePath`：实际保存路径
- `rowCount`：导出的行数
- `fileSize`：文件大小

**示例：**
```
导出 users 表为 JSON 文件
```

#### create_table
创建表。

**参数：**
- `table`（必填）：表名
- `columns`（必填）：列定义数组
  - `name`：列名
  - `type`：数据类型
  - `nullable`：是否可空
  - `primaryKey`：是否为主键
  - `defaultValue`：默认值
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `success`：是否成功
- `tableName`：表名

**示例：**
```
创建一个 products 表，包含 id、name、price 列
```

#### drop_table
删除表。

**参数：**
- `table`（必填）：表名
- `ifExists`（可选）：使用 IF EXISTS 避免表不存在时报错
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `success`：是否成功
- `tableName`：表名

**示例：**
```
删除 temp_data 表
```

### 数据分析（v2.0.0 新增）

#### get_table_stats
获取表的统计信息。

**参数：**
- `table`（必填）：表名
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `tableName`：表名
- `rowCount`：行数
- `columns`：列数
- `indexes`：索引列表
- `size`：表大小

**示例：**
```
显示 orders 表的统计信息
```

#### preview_data
分页预览表数据。

**参数：**
- `table`（必填）：表名
- `page`（可选）：页码（默认：1）
- `pageSize`（可选）：每页行数（默认：50）
- `orderBy`（可选）：排序列
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `rows`：数据行
- `currentPage`：当前页码
- `totalPages`：总页数
- `totalRows`：总行数

**示例：**
```
预览 users 表的第 2 页，每页 20 条
```

#### sample_data
随机采样数据。

**参数：**
- `table`（必填）：表名
- `count`（可选）：采样数量（默认：10）
- `connectionKey`（可选）：连接 key（如果不指定，使用默认连接）

**注意：** 所有工具都支持 `connectionKey` 参数来指定使用哪个连接。如果不提供，则使用默认连接（如果有）。

**返回：**
- `rows`：采样的数据行
- `sampleCount`：实际采样数量

**示例：**
```
从 orders 表随机采样 5 条数据
```

## 安全性

v3.0.0+ 版本中，动态创建的连接默认允许所有操作（读取、写入、DDL）。请在使用 `create_connection` 工具时确保连接凭据的安全性。

如需限制操作权限，建议在数据库层面配置用户权限。

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 开发模式运行
npm run dev

# 运行生产构建
npm start
```

## 版本历史

### v3.0.0
- 新增动态连接管理功能
- 新增 4 个连接管理工具：create_connection, list_connections, close_connection, close_all_connections
- 所有工具支持 connectionKey 参数指定连接
- 移除 EASYDB_ALLOW_WRITE 和 EASYDB_ALLOW_DDL 限制

### v2.0.0
- 升级到 MCP SDK 1.25.3
- 迁移到新的 McpServer API
- 新增 9 个工具：execute_transaction, batch_insert, batch_update, export_data, create_table, drop_table, get_table_stats, preview_data, sample_data
- 新增文件工具模块

### v1.0.0
- 初始版本
- 支持 MySQL、PostgreSQL、SQLite
- 4 个基础工具：list_tables, describe_table, execute_query, execute_sql

## 许可证

MIT