npm package: @hamaster/mysql-mcp-server
Description: MySQL MCP Server - 提供MySQL数据库操作工具
Latest version: 1.0.2

# MySQL MCP Server

一个用于操作MySQL数据库的Model Context Protocol (MCP)服务器。提供列数据库、列表、查询表结构、执行SQL查询和更新等功能。

## 功能特性

- 列出MySQL服务器上的所有数据库
- 列出指定数据库中的所有表
- 获取表的详细结构（字段名称、类型、注释等）
- 执行SELECT查询并返回JSON格式结果
- 执行INSERT、UPDATE、DELETE等操作并返回执行结果

## 安装

### 全局安装（推荐）

```bash
npm install -g mysql-mcp-server
```

### 本地安装

```bash
cd mysql-mcp-server
npm install
```

## 配置

创建 `.env` 文件并配置MySQL连接参数：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
```

### 环境变量说明

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| MYSQL_HOST | 否 | localhost | MySQL服务器地址 |
| MYSQL_PORT | 否 | 3306 | MySQL端口 |
| MYSQL_USER | 否 | root | MySQL用户名 |
| MYSQL_PASSWORD | 否 | (空) | MySQL密码 |
| MYSQL_DATABASE | 否 | (空) | 默认数据库名称 |

## 使用方法

### 通过npx运行

```bash
npx -y mysql-mcp-server
```

### 在MCP Hub中配置

在MCP Hub的配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "myapp"
      }
    }
  }
}
```

### 本地运行

```bash
npm start
```

## 可用工具

### 1. mysql_list_databases
列出MySQL服务器上的所有数据库。

**参数：**
- 无需参数

**返回示例：**
```json
{
  "success": true,
  "databases": [
    "information_schema",
    "mysql",
    "performance_schema",
    "myapp"
  ]
}
```

### 2. mysql_list_tables
列出指定数据库中的所有表。

**参数：**
- `database` (string, 必填): 数据库名称

**示例：**
```
数据库: myapp
```

**返回示例：**
```json
{
  "success": true,
  "database": "myapp",
  "tables": ["users", "products", "orders"]
}
```

### 3. mysql_describe_table
获取表的详细结构信息，包括字段名称、数据类型、是否为空、键、默认值、注释等。

**参数：**
- `database` (string, 必填): 数据库名称
- `table` (string, 必填): 表名称

**示例：**
```
数据库: myapp
表: users
```

**返回示例：**
```json
{
  "success": true,
  "database": "myapp",
  "table": "users",
  "table_comment": "用户表",
  "columns": [
    {
      "field": "id",
      "type": "int(11)",
      "null": false,
      "key": "PRI",
      "default": null,
      "extra": "auto_increment"
    },
    {
      "field": "name",
      "type": "varchar(100)",
      "null": false,
      "key": "",
      "default": null,
      "extra": ""
    },
    {
      "field": "email",
      "type": "varchar(255)",
      "null": false,
      "key": "UNI",
      "default": null,
      "extra": ""
    },
    {
      "field": "created_at",
      "type": "timestamp",
      "null": false,
      "key": "",
      "default": "CURRENT_TIMESTAMP",
      "extra": ""
    }
  ]
}
```

### 4. mysql_query
执行SELECT查询语句，返回JSON格式的查询结果。

**参数：**
- `database` (string, 必填): 数据库名称
- `sql` (string, 必填): SQL SELECT查询语句

**示例：**
```
数据库: myapp
SQL: SELECT id, name, email FROM users WHERE age > 18 LIMIT 10
```

**返回示例：**
```json
{
  "success": true,
  "database": "myapp",
  "row_count": 3,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    {
      "id": 3,
      "name": "Bob Johnson",
      "email": "bob@example.com"
    }
  ]
}
```

### 5. mysql_execute
执行INSERT、UPDATE、DELETE等非查询SQL语句，返回执行结果。

**参数：**
- `database` (string, 必填): 数据库名称
- `sql` (string, 必填): SQL语句

**示例：**
```
数据库: myapp
SQL: INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')
```

**返回示例：**
```json
{
  "success": true,
  "database": "myapp",
  "affected_rows": 1,
  "insert_id": 4,
  "message": "INSERT执行成功，影响1行"
}
```

**安全说明：**
- 不允许执行包含DROP、TRUNCATE、ALTER、CREATE等危险关键词的语句
- 所有操作都会验证SQL语句类型

## 完整工作流程示例

1. **列出所有数据库**
   - 工具: `mysql_list_databases`

2. **查看某个数据库的表**
   - 工具: `mysql_list_tables`
   - 参数: `database: myapp`

3. **查看表结构**
   - 工具: `mysql_describe_table`
   - 参数: `database: myapp, table: users`

4. **查询数据**
   - 工具: `mysql_query`
   - 参数: `database: myapp, sql: SELECT * FROM users WHERE id = 1`

5. **插入数据**
   - 工具: `mysql_execute`
   - 参数: `database: myapp, sql: INSERT INTO users (name, email) VALUES ('John', 'john@example.com')`

6. **更新数据**
   - 工具: `mysql_execute`
   - 参数: `database: myapp, sql: UPDATE users SET email = 'newemail@example.com' WHERE id = 1`

## 技术栈

- Node.js >= 18.0.0
- @modelcontextprotocol/sdk ^1.25.2
- mysql2 ^3.9.0

## 安全特性

- SQL注入防护：使用参数化查询
- 操作权限控制：限制危险的数据库操作（DROP、TRUNCATE等）
- 错误处理：完善的错误捕获和返回机制
- 连接池管理：使用MySQL连接池提高性能和稳定性

## 故障排除

### 连接失败
- 检查 `.env` 文件中的连接参数是否正确
- 确认MySQL服务器是否正在运行
- 检查防火墙设置

### 权限错误
- 确认MySQL用户是否有相应的数据库访问权限
- 检查用户是否有SELECT、INSERT、UPDATE、DELETE权限

### SQL执行错误
- 检查SQL语法是否正确
- 确认表名和字段名是否存在
- 查看返回的错误信息以获取详细原因

## 许可证

MIT