# 小檬 MySQL MCP 服务器

**Repository Path**: t0xm/xiaomeng-mysql-servers-mcp

## Basic Information

- **Project Name**: 小檬 MySQL MCP 服务器
- **Description**: 这是一个基于 Model Context Protocol (MCP) 的 MySQL 数据库连接服务，允许通过 MCP 协议连接和操作 MySQL 数据库。本项目提供了一个完整的 MCP 服务器实现，专门用于 MySQL 数据库操作。它支持连接到本地或远程 MySQL 服务器，执行 SQL 语句，并返回格式化的结果。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-02
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小檬 MySQL MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的 MySQL 数据库连接服务，允许通过 MCP 协议连接和操作 MySQL 数据库。

## 项目概述

本项目提供了一个完整的 MCP 服务器实现，专门用于 MySQL 数据库操作。它支持连接到本地或远程 MySQL 服务器，执行 SQL 语句，并返回格式化的结果。

## 主要功能

- **数据库连接管理**：支持连接池管理，提高性能
- **SQL 语句执行**：支持所有类型的 SQL 语句（SELECT、INSERT、UPDATE、DELETE 等）
- **连接测试**：提供数据库连接测试功能
- **错误处理**：完善的错误处理和异常捕获
- **参数配置**：灵活的数据库连接参数配置
- **结果格式化**：返回结构化的查询结果

## 系统要求

- Node.js >= 18.0.0
- MySQL 服务器（本地或远程）

## 安装步骤

### 1. 克隆项目

```bash
git clone https://gitee.com/t0xm/xiaomeng-mysql-servers-mcp
cd xiaomeng-mysql-servers-mcp
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置 MCP 客户端

在你的 MCP 客户端配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "xiaomeng-mysql-server": {
      "command": "node",
      "args": [
        "d:\\path\\to\\xiaomeng-mysql-servers-mcp\\index.js"
      ]
    }
  }
}
```

## 使用方法

### 启动服务器

```bash
npm start
```

或者

```bash
node index.js
```

## 可用工具

### 1. execute_sql - 执行 SQL 语句

执行 MySQL SQL 语句并返回结果。

#### 参数说明

| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|---------|
| `host` | string | 否 | localhost | MySQL 服务器地址 |
| `port` | number | 否 | 3306 | MySQL 服务器端口 |
| `database` | string | 是 | - | 数据库名称 |
| `user` | string | 否 | root | 用户名 |
| `password` | string | 否 | "" | 密码 |
| `sql` | string | 是 | - | 要执行的 SQL 语句 |

#### 返回值说明

**成功时返回：**
```json
{
  "success": true,
  "data": [...],           // 查询结果数据
  "fields": [...],         // 字段信息
  "rowCount": 10,          // 返回行数
  "affectedRows": 1,       // 影响行数（INSERT/UPDATE/DELETE）
  "insertId": 123          // 插入ID（INSERT时）
}
```

**失败时返回：**
```json
{
  "success": false,
  "error": "错误信息",
  "code": "ER_NO_SUCH_TABLE",
  "errno": 1146,
  "sqlState": "42S02"
}
```

#### 使用示例

```javascript
// 查询数据
{
  "host": "localhost",
  "port": 3306,
  "database": "test_db",
  "user": "root",
  "password": "password",
  "sql": "SELECT * FROM users WHERE age > 18"
}

// 插入数据
{
  "database": "test_db",
  "sql": "INSERT INTO users (name, email, age) VALUES ('张三', 'zhangsan@example.com', 25)"
}

// 更新数据
{
  "database": "test_db",
  "sql": "UPDATE users SET age = 26 WHERE name = '张三'"
}

// 删除数据
{
  "database": "test_db",
  "sql": "DELETE FROM users WHERE age < 18"
}
```

### 2. test_connection - 测试数据库连接

测试 MySQL 数据库连接是否正常。

#### 参数说明

| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|---------|
| `host` | string | 否 | localhost | MySQL 服务器地址 |
| `port` | number | 否 | 3306 | MySQL 服务器端口 |
| `database` | string | 是 | - | 数据库名称 |
| `user` | string | 否 | root | 用户名 |
| `password` | string | 否 | "" | 密码 |

#### 返回值说明

**连接成功时：**
```json
{
  "success": true,
  "message": "数据库连接测试成功",
  "config": {
    "host": "localhost",
    "port": 3306,
    "database": "test_db",
    "user": "root"
  }
}
```

**连接失败时：**
```json
{
  "success": false,
  "message": "数据库连接测试失败",
  "error": "Access denied for user 'root'@'localhost'",
  "config": {
    "host": "localhost",
    "port": 3306,
    "database": "test_db",
    "user": "root"
  }
}
```

#### 使用示例

```javascript
// 测试本地数据库连接
{
  "database": "test_db",
  "user": "root",
  "password": "password"
}

// 测试远程数据库连接
{
  "host": "192.168.1.100",
  "port": 3306,
  "database": "production_db",
  "user": "app_user",
  "password": "secure_password"
}
```

## 技术架构

### 核心组件

1. **MySQLManager 类**：负责数据库连接池管理和 SQL 执行
2. **MCP Server**：处理 MCP 协议通信
3. **连接池**：使用 mysql2 的连接池功能，提高性能
4. **错误处理**：完善的异常捕获和错误信息返回

### 依赖包

- `@modelcontextprotocol/sdk`: MCP 协议 SDK
- `mysql2`: MySQL 数据库驱动（支持 Promise）

## 安全注意事项

1. **密码安全**：不要在代码中硬编码数据库密码
2. **SQL 注入**：虽然使用了参数化查询，但仍需注意 SQL 语句的安全性
3. **网络安全**：在生产环境中使用 SSL 连接
4. **权限控制**：为应用创建专用的数据库用户，限制权限

## 性能优化

1. **连接池**：使用连接池减少连接开销
2. **查询优化**：编写高效的 SQL 语句
3. **索引使用**：确保数据库表有适当的索引
4. **批量操作**：对于大量数据操作，考虑使用批量处理

## 故障排除

### 常见问题

1. **连接被拒绝**
   - 检查 MySQL 服务是否运行
   - 验证主机地址和端口
   - 确认用户名和密码正确

2. **数据库不存在**
   - 确认数据库名称正确
   - 检查用户是否有访问该数据库的权限

3. **SQL 语法错误**
   - 检查 SQL 语句语法
   - 确认表名和字段名正确

### 调试模式

可以通过查看控制台输出来调试问题：

```bash
node index.js
```

## 开发信息

- **作者**：田小檬
- **邮箱**：admin@lmwa.cn
- **版本**：1.0
- **创建日期**：2025/9/2 22:40:10
- **许可证**：Apache 2.0 

## 更新日志

### v1.0 (2025/9/2)
- 初始版本发布
- 实现基本的 MySQL 连接和查询功能
- 添加连接测试工具
- 完善错误处理机制

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 许可证

本项目采用 Apache 2.0 许可证。