# MySQL_SSE_MCP

**Repository Path**: jerryzu/MySQL_SSE_MCP

## Basic Information

- **Project Name**: MySQL_SSE_MCP
- **Description**: MySQL MCP 是一个基于 Model Context Protocol (MCP) 的 MySQL 数据库管理工具，它允许大型语言模型通过标准化的协议与 MySQL 数据库进行交互。

- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MySQL MCP 服务器

MySQL MCP 是一个基于 Model Context Protocol (MCP) 的 MySQL 数据库管理工具，它允许大型语言模型通过标准化的协议与 MySQL 数据库进行交互。

## 项目概述

MCP (Model Context Protocol) 是由 Anthropic 开发的开源协议，旨在帮助大型语言模型(LLM)与外部数据源和工具无缝集成。本项目使用 FastMCP 实现了 MCP 协议，专门用于 MySQL 数据库的操作和管理。

### 功能特性

- 获取 MySQL 服务器上的所有数据库列表
- 获取指定数据库中的表列表
- 获取表结构信息（支持单个表或多个表）
- 执行 SQL 查询语句
- 执行非查询 SQL 语句（INSERT、UPDATE、DELETE 等）

## 项目结构

```
MySQL/
├── Dockerfile              # Docker 容器配置文件
├── docker-compose.yml      # Docker Compose 配置文件
├── .env                    # 环境变量配置文件
├── main.py                 # MCP 服务器主程序
├── pyproject.toml          # Python 项目配置文件
├── uv.toml                 # UV 包管理器配置文件
├── uv.lock                 # UV 锁定文件
├── Tools/                  # 工具模块目录
│   ├── MySQLClient.py      # MySQL 客户端操作类
│   └── __init__.py
└── README.md               # 本文档
```

## 核心组件

### 1. MySQLClient.py

位于 `Tools/MySQLClient.py`，包含两个核心类：

- `MySQLManager`: 负责管理 MySQL 数据库连接
- `MySQLClient`: 提供数据库操作的各种方法

### 2. main.py

MCP 服务器的主程序，定义了以下工具：

- `get_databases`: 获取数据库列表
- `get_tables`: 获取数据库中的表列表
- `get_table_structure`: 获取表结构信息
- `execute_query`: 执行 SQL 查询语句
- `execute_non_query`: 执行非查询 SQL 语句

## 部署方式

### 方式一：使用 Docker Compose（推荐）

1. 确保已安装 Docker 和 Docker Compose

2. 克隆项目到本地：
```bash
git clone https://gitee.com/ezemeti/MySQL_SSE_MCP.git
cd MySQL_SSE_MCP
```

3. 启动服务：
```bash
docker-compose up -d
```

4. 服务将在 `http://localhost:8001` 上运行（端口可在 `.env` 文件中修改）

### 方式二：使用 UV 直接运行

1. 确保已安装 Python 3.13+ 和 UV

2. 克隆项目到本地：
```bash
git clone https://gitee.com/ezemeti/MySQL_SSE_MCP.git
cd MySQL_SSE_MCP
```

3. 安装依赖：
```bash
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
uv sync
```

4. 运行服务：
```bash
uv run python main.py
```

### 方式三：使用 Docker

1. 构建镜像：
```bash
docker build -t mysql-mcp .
```

2. 运行容器：
```bash
docker run -d -p 8001:8001 --name mysql-mcp mysql-mcp
```

## 环境配置

项目使用 `.env` 文件进行环境配置：

```env
# 服务端口配置
PORT=8001
HOST=0.0.0.0
```

## 连接到 MCP 客户端

要将 MySQL MCP 服务器连接到支持 MCP 的客户端（如 Claude Desktop），需要在客户端配置中添加以下内容：

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "url": "http://127.0.0.1:8001/sse"
    }
  }
}
```

### Claude Desktop 配置示例

1. 找到 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`

2. 在配置文件中添加以下内容：

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "url": "http://127.0.0.1:8001/sse"
    }
  }
}
```

3. 重启 Claude Desktop

## 使用示例

### 获取数据库列表

向 AI 助手发送请求：
"请获取 MySQL 服务器上的所有数据库列表"

AI 将调用 `get_databases` 工具，需要提供 MySQL 连接信息：
```json
{
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "your_password"
}
```

### 获取表结构

"请获取 mydb 数据库中 users 表的结构"

AI 将调用 `get_table_structure` 工具，参数如下：
```json
{
  "mysql_manager": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_password"
  },
  "table": "users",
  "database": "mydb"
}
```

### 执行查询

"请查询 mydb 数据库中 users 表的所有记录"

AI 将调用 `execute_query` 工具，参数如下：
```json
{
  "mysql_manager": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_password"
  },
  "query": "SELECT * FROM users",
  "database": "mydb"
}
```

### 执行非查询操作

"请向 mydb 数据库的 users 表插入一条记录"

AI 将调用 `execute_non_query` 工具，参数如下：
```json
{
  "mysql_manager": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_password"
  },
  "query": "INSERT INTO users (name, email) VALUES (%s, %s)",
  "database": "mydb",
  "params": ["John Doe", "john@example.com"]
}
```

### 批量插入数据

"请向 mydb 数据库的 users 表批量插入多条记录"

AI 将调用 `execute_non_query` 工具，参数如下：
```json
{
  "mysql_manager": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_password"
  },
  "query": "INSERT INTO users (name, email) VALUES (%s, %s)",
  "database": "mydb",
  "params": [
    ["John Doe", "john@example.com"],
    ["Jane Smith", "jane@example.com"],
    ["Bob Johnson", "bob@example.com"]
  ]
}
```

批量操作会自动检测，当params参数是列表的列表时，会自动执行批量操作，返回结果包含总影响行数和批次数：
```json
{
  "affected_rows": 3,
  "batch_count": 3,
  "message": "成功执行批量操作，共3批，影响3行"
}
```

## 技术栈

- Python 3.13+
- FastMCP 2.12.4+ - MCP 框架
- PyMySQL 1.1.2+ - MySQL 连接库
- python-dotenv 1.1.1+ - 环境变量管理
- Docker - 容器化部署
- UV - Python 包管理器

## 开发指南

### 本地开发

1. 克隆项目：
```bash
git clone https://gitee.com/ezemeti/MySQL_SSE_MCP.git
cd MySQL_SSE_MCP
```

2. 创建虚拟环境：
```bash
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
uv venv
uv venv activate  # Linux/Mac
.venv\Scripts\activate     # Windows
```

3. 安装依赖：
```bash
uv sync
```

4. 运行开发服务器：
```bash
uv run python main.py
```

### 添加新功能

1. 在 `Tools/MySQLClient.py` 中添加新的数据库操作方法
2. 在 `main.py` 中使用 `@mcp.tool` 装饰器注册新的工具
3. 更新文档

## 注意事项

1. 确保数据库连接信息安全，不要在代码中硬编码密码
2. 在生产环境中使用环境变量或密钥管理系统
3. 定期更新依赖库以获取安全修复
4. 对于大型数据库，考虑添加查询限制和分页功能

## 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

## 贡献

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

## 相关链接

- [FastMCP 文档](https://fastmcp.wiki/zh/getting-started/welcome)