npm package: @muybaby/mysql-mcp-server
Description: MySQL Model Context Protocol (MCP) server for AI assistants like Claude Desktop and Cherry Studio
Author: Your Name
Latest version: 1.0.0

# MySQL MCP Server

基于 Model Context Protocol (MCP) 的 MySQL 数据库服务器，提供安全、标准化的 MySQL 数据库访问接口。

## 功能特性

### 🔧 数据库管理工具
- **连接测试**: 测试 MySQL 数据库连接
- **连接配置**: 设置和管理数据库连接参数
- **数据库操作**: 创建数据库、查看数据库列表
- **表管理**: 查看表列表、表结构、表详细信息

### 📊 查询执行
- **SQL 查询**: 执行任意 SQL 查询（SELECT、INSERT、UPDATE、DELETE 等）
- **结果格式化**: JSON 格式返回查询结果
- **错误处理**: 详细的错误信息和状态反馈

### 🛡️ 安全特性
- **连接验证**: 执行前验证数据库连接
- **错误隔离**: 安全的错误处理，避免敏感信息泄露
- **参数化查询**: 支持安全的 SQL 执行

## 安装和设置

### 系统要求
- Python 3.13+
- MySQL 5.7+ 或 MariaDB 10.3+
- uv 包管理器

### 1. 克隆和安装

```bash
# 进入项目目录
cd mysql-mcp-server

# 安装依赖（已完成）
uv add "mcp[cli]" mysql-connector-python SQLAlchemy
```

### 2. 配置环境变量

复制环境变量示例文件并自定义配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password_here
MYSQL_DATABASE=your_default_database
```

### 3. 测试服务器

```bash
# 运行服务器
uv run mysql_mcp_server.py
```

## Claude Desktop 集成

### 配置 Claude Desktop

1. 打开 Claude Desktop 配置文件：
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. 添加 MySQL MCP 服务器配置：

```json
{
  "mcpServers": {
    "mysql-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mysql-mcp-server",
        "run",
        "mysql_mcp_server.py"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}
```

3. 重启 Claude Desktop

### 验证集成

在 Claude Desktop 中查找 "搜索和工具" 图标，应该可以看到以下工具：

- `test_connection` - 测试数据库连接
- `set_connection` - 设置连接配置
- `execute_query` - 执行 SQL 查询
- `show_databases` - 显示数据库列表
- `show_tables` - 显示表列表
- `describe_table` - 描述表结构
- `get_table_info` - 获取表详细信息
- `create_database` - 创建数据库
- `get_connection_info` - 获取连接信息

## 使用示例

### 1. 测试连接

```
请帮我测试连接到本地 MySQL 数据库，用户名是 root，密码是 123456
```

### 2. 查看数据库

```
请显示所有数据库列表
```

### 3. 执行查询

```
请在 test_db 数据库中查询 users 表的所有记录
```

### 4. 创建表

```
请在 test_db 数据库中创建一个名为 employees 的表，包含 id、name、email、department 字段
```

## 可用工具

### `test_connection`
测试 MySQL 数据库连接

**参数:**
- `host` (str): MySQL 服务器地址，默认 "localhost"
- `port` (int): MySQL 端口，默认 3306
- `user` (str): 用户名，默认 "root"
- `password` (str): 密码
- `database` (str): 数据库名（可选）

**返回:** 连接状态和 MySQL 版本信息

### `set_connection`
设置默认数据库连接配置

**参数:** 同 `test_connection`

**返回:** 配置设置状态

### `execute_query`
执行 SQL 查询

**参数:**
- `query` (str): 要执行的 SQL 查询
- `database` (str): 目标数据库（可选）

**返回:** JSON 格式的查询结果

### `show_databases`
显示所有数据库

**返回:** 数据库列表的 JSON 格式

### `show_tables`
显示数据库中的所有表

**参数:**
- `database` (str): 数据库名（可选，使用默认配置）

**返回:** 表列表的 JSON 格式

### `describe_table`
获取表结构信息

**参数:**
- `table_name` (str): 表名
- `database` (str): 数据库名（可选）

**返回:** 表结构的 JSON 格式

### `get_table_info`
获取表的详细信息（结构、索引、统计）

**参数:**
- `table_name` (str): 表名
- `database` (str): 数据库名（可选）

**返回:** 表详细信息的 JSON 格式

### `create_database`
创建新数据库

**参数:**
- `database_name` (str): 数据库名
- `charset` (str): 字符集，默认 "utf8mb4"

**返回:** 创建状态

### `get_connection_info`
获取当前连接配置信息

**返回:** 连接配置（密码已隐藏）

## 测试数据

项目包含 `test_queries.sql` 文件，提供了完整的测试数据和示例查询：

```bash
# 在 MySQL 中执行测试数据
mysql -u root -p < test_queries.sql
```

## 故障排除

### 常见问题

1. **连接失败**
   - 检查 MySQL 服务是否运行
   - 验证用户名和密码
   - 确认防火墙设置

2. **Claude Desktop 无法识别服务器**
   - 检查配置文件路径是否正确
   - 确认 `uv` 命令可用
   - 重启 Claude Desktop

3. **权限错误**
   - 确认 MySQL 用户具有必要权限
   - 检查数据库访问权限

### 调试模式

```bash
# 使用 MCP Inspector 测试服务器
uv run mcp dev mysql_mcp_server.py
```

## 安全注意事项

- 🔒 不要在配置文件中硬编码密码
- 🔒 使用环境变量存储敏感信息
- 🔒 定期轮换数据库密码
- 🔒 限制数据库用户权限
- 🔒 在生产环境中使用 SSL 连接

## 许可证

MIT License

## 贡献

欢迎提交 Issues 和 Pull Requests！

## 更新日志

### v0.1.0
- 初始版本
- 基本的 MySQL 连接和查询功能
- Claude Desktop 集成支持
- 完整的数据库管理工具