# 🚀 MySQL MCP Server

[![npm version](https://badge.fury.io/js/@pickstar-2002%2Fmysql-mcp.svg)](https://badge.fury.io/js/@pickstar-2002%2Fmysql-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)

> 🎯 **让 AI 助手轻松管理 MySQL 数据库的强大 MCP 工具**

基于 Model Context Protocol (MCP) 的 MySQL 数据库管理工具，让您能够通过 AI 助手（如 Claude）执行各种数据库操作，无需手动编写 SQL 语句。

## ✨ 功能特性

### 🔗 连接管理
- ✅ 灵活的数据库连接配置
- ✅ 支持环境变量和参数配置
- ✅ 连接状态检查和管理
- ✅ 安全的连接池管理

### 🗄️ 数据库操作
- ✅ 列出所有数据库
- ✅ 创建数据库（支持字符集和排序规则）
- ✅ 删除数据库
- ✅ 数据库信息查询

### 📊 表操作
- ✅ 列出指定数据库的所有表
- ✅ 查看表结构和字段详情
- ✅ 创建表（通过 SQL 语句）
- ✅ 删除表
- ✅ 表信息统计

### 📝 数据操作
- ✅ 执行 SQL 查询（支持参数化查询）
- ✅ 插入数据（支持批量插入）
- ✅ 更新数据
- ✅ 删除数据
- ✅ 数据导出到 CSV/JSON 文件
- ✅ 从 CSV/JSON 文件导入数据

### 🛡️ 安全特性
- ✅ SQL 注入防护
- ✅ 危险操作检测
- ✅ 参数化查询支持
- ✅ 权限控制建议

## 📦 安装

### 方式一：直接使用（推荐）

在您的 MCP 客户端配置中直接使用 `@latest` 标签：

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": ["@pickstar-2002/mysql-mcp@latest"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "mysql"
      }
    }
  }
}
```

### 方式二：全局安装

```bash
npm install -g @pickstar-2002/mysql-mcp@latest
```

### 方式三：项目安装

```bash
npm install @pickstar-2002/mysql-mcp@latest
```

## 🚀 快速开始

### 1. 配置环境变量

创建 `.env` 文件：

```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=mysql

# 可选配置
MYSQL_CONNECTION_LIMIT=10
MYSQL_TIMEOUT=60000
```

### 2. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": ["@pickstar-2002/mysql-mcp@latest"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "mysql"
      }
    }
  }
}
```

### 3. 在其他 MCP 客户端中配置

对于支持 MCP 协议的其他客户端：

```json
{
  "command": "npx",
  "args": ["@pickstar-2002/mysql-mcp@latest"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "your_password"
  }
}
```

## 💡 使用示例

配置完成后，您可以在 AI 助手中使用自然语言进行数据库操作：

### 🔗 连接数据库
```
请连接到我的 MySQL 数据库，主机是 localhost，用户名是 root
```

### 📋 查看数据库列表
```
请列出所有的数据库
```

### 🆕 创建数据库
```
请创建一个名为 test_db 的数据库，使用 utf8mb4 字符集
```

### 🔍 查看表结构
```
请查看 users 表的结构和字段信息
```

### 📊 执行查询
```
请查询 users 表中所有年龄大于 18 的用户，按注册时间排序
```

### ➕ 插入数据
```
请向 users 表插入一条新记录：name='张三', age=25, email='zhangsan@example.com'
```

### 📤 导出数据
```
请将 users 表的数据导出为 CSV 文件到 /tmp/users.csv
```

### 📥 导入数据
```
请从 /tmp/users.csv 文件导入数据到 users 表
```

## 🛠️ API 工具列表

| 工具名称 | 功能描述 |
|---------|---------|
| `mysql_connect` | 连接到 MySQL 数据库 |
| `mysql_disconnect` | 断开数据库连接 |
| `mysql_list_databases` | 列出所有数据库 |
| `mysql_create_database` | 创建数据库 |
| `mysql_drop_database` | 删除数据库 |
| `mysql_list_tables` | 列出表 |
| `mysql_describe_table` | 查看表结构 |
| `mysql_create_table` | 创建表 |
| `mysql_drop_table` | 删除表 |
| `mysql_query` | 执行 SQL 查询 |
| `mysql_insert` | 插入数据 |
| `mysql_update` | 更新数据 |
| `mysql_delete` | 删除数据 |
| `mysql_export_data` | 导出数据 |
| `mysql_import_data` | 导入数据 |

## 🔧 配置选项

### 环境变量

| 变量名 | 描述 | 默认值 | 必需 |
|-------|------|--------|------|
| `MYSQL_HOST` | MySQL 服务器地址 | `localhost` | ✅ |
| `MYSQL_PORT` | MySQL 端口号 | `3306` | ❌ |
| `MYSQL_USER` | 用户名 | `root` | ✅ |
| `MYSQL_PASSWORD` | 密码 | - | ✅ |
| `MYSQL_DATABASE` | 默认数据库 | - | ❌ |
| `MYSQL_CONNECTION_LIMIT` | 连接池大小 | `10` | ❌ |
| `MYSQL_TIMEOUT` | 连接超时时间(ms) | `60000` | ❌ |

## 🛡️ 安全注意事项

1. **🔐 密码保护**: 确保 `.env` 文件不被提交到版本控制系统
2. **🚫 SQL 注入防护**: 工具内置基础 SQL 安全检查，建议使用参数化查询
3. **👤 权限控制**: 建议为 MCP 服务器创建专用 MySQL 用户并限制权限
4. **🌐 网络安全**: 生产环境中确保 MySQL 服务器网络访问安全
5. **📝 操作审计**: 重要操作前会进行安全提示

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源协议。

## 📞 联系方式

如有问题或建议，欢迎联系：

**微信**: pickstar_loveXX

---

⭐ 如果这个项目对您有帮助，请给个 Star 支持一下！