mysql-mcp-服务器

Name: mysql-mcp-服务器
Author: Mineru98

作者：Mineru9828 星标更新：2025-03-23

安装使用来源：spider==github.com

项目介绍

mysql-mcp-server

Korean README.md

0. 执行

使用Docker运行

根据需要更改数据库连接信息。

docker run -d --name mcp-mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=mcpTest1234!!! \
  -e MYSQL_DATABASE=mcp_test \
  -e MCP_PORT=8081 \
  -p 3306:3306 mineru/mcp-mysql:1.0.0

使用Docker Compose运行

这将使用预配置设置进行操作。

docker-compose up -d

直接使用Python运行

pip install -r requirements.txt
python mysql_mcp_server/main.py run

Cursor配置

MCP功能从Cursor版本0.46开始可用。

此外，MCP特性仅对Cursor Pro账户用户开放。

Cursor设置

工具添加提示

添加工具
- execute函数实现实际逻辑执行（服务层）。
- @tool装饰器帮助将工具注册到MCP（控制器层）。
解释
- mysql_mcp_server/executors目录下的每个文件代表一个单独的工具。
- 如果添加了新工具，必须在mysql_mcp_server/executors/__init__.py中导入，并包含在__all__数组中。
- 这确保模块自动注册到TOOLS_DEFINITION变量。

flowchart LR;
    A[AI模型] -->|请求工具列表| B[MCP服务器]
    B -->|返回可用工具| A

    A -->|请求特定工具执行| B
    B -->|调用相应的执行器| C[执行器]
    
    subgraph 执行器
        C1[execute_create_table] -->|创建表| D
        C2[execute_desc_table] -->|查看表结构| D
        C3[execute_explain] -->|查询执行计划| D
        C4[execute_insert_query] -->|执行INSERT查询| D
        C5[execute_insight_starter] -->|检查用于生成报告的模式| D
        C6[execute_invoke_viz_pro] -->|可视化图表推荐| D
        C7[execute_select_query] -->|执行SELECT查询| D
        C8[execute_show_tables] -->|检索表列表| D
    end

    D[DatabaseManager] -->|连接到MySQL| E[MySQL 8.0]

    E -->|返回结果| D
    D -->|发送结果| C
    C -->|返回结果| B
    B -->|返回执行结果| A

🚧 开发路线图 🚧

⚙️ 参数选项
- [ ] 🔧 每个工具的启用/禁用开关：提供减少输入上下文成本的功能 💰
- [ ] 🔒 查询安全级别设置：提供可选控制可能损害资产价值的功能，如DROP、DELETE、UPDATE 🚫
✨ 功能
- [x] 📊 数据分析报告生成：提供优化模型以根据用户请求适当选择各种图表的报告生成功能 📈
  - [x] 📝 预定形式的报告能力
  - [ ] 🖌️ 报告模板多样化
- [ ] 🗄️ 扩展Text2SQL支持
- [ ] 🌐 SSH连接支持：通过SSH启用安全远程访问以进行高级操作 🔑
- [ ] 📥 文件提取功能
  - [ ] 📄 CSV
  - [ ] 📑 JSON
  - [ ] 📉 Excel

1. 概述

MCP MySQL服务器是一个基于MCP（模型上下文协议）的MySQL数据库操作服务器应用程序。该服务器提供了允许AI模型与MySQL数据库交互的工具。

2. 系统配置

2.1 关键组件

MCP服务器：与AI模型通信的FastMCP服务器
MySQL数据库：管理和存储数据
工具：执行数据库操作的执行器

2.2 技术栈

语言：Python
数据库：MySQL 8.0
关键库：
- mcp：实现AI通信的模型上下文协议
- PyMySQL：连接到MySQL并执行查询
- pandas：处理和分析数据
- python-dotenv：管理环境变量
- fire：实现命令行界面

2.3 部署环境

通过Docker和Docker Compose容器化部署
端口：8081（MCP服务器），3306（MySQL）

3. 目录结构

MCPBoilerPlate/
├── mysql_mcp_server/           # 主应用目录
│   ├── executors/              # 数据库操作执行器
│   │   ├── create_table.py     # 创建表的工具
│   │   ├── desc_table.py       # 查看表结构的工具
│   │   ├── explain.py          # 提供查询执行计划的工具
│   │   ├── insert_query.py     # 执行INSERT查询的工具
│   │   ├── insight_starter.py  # 用于写报告的模式验证工具
│   │   ├── invoke_viz_pro.py   # 提供可视化图表推荐的工具
│   │   ├── select_query.py     # 执行SELECT查询的工具
│   │   └── show_tables.py      # 检索表列表的工具
│   ├── helper/                 # 实用模块
│   │   ├── db_conn_helper.py   # 管理数据库连接
│   │   ├── logger_helper.py    # 日志实用工具
│   │   └── tool_decorator.py   # 工具装饰器
│   └── main.py                 # 应用入口点
├── docker-compose.yml          # Docker Compose配置
├── Dockerfile                  # Docker镜像构建设置
├── requirements.txt            # 依赖包列表
└── .env.example                # 示例环境变量文件

4. 架构设计

4.1 层次结构

接口层：MCP服务器（FastMCP）
业务逻辑层：处理器和执行器
数据访问层：数据库连接和查询执行

4.2 关键类和模块

MySQLMCPServer：初始化并运行MCP服务器的主要服务器类
DatabaseManager：基于单例模式的数据库连接管理器
执行器：数据库操作工具集合
- execute_create_table：创建表
- execute_desc_table：检查表结构
- execute_explain：提供查询执行计划
- execute_insert_query：执行INSERT查询
- execute_select_query：执行SELECT查询
- execute_show_tables：检索表列表

4.3 通信流程

AI模型向MCP服务器请求可用工具列表。
服务器返回可用工具列表。
AI模型请求特定工具的执行。
服务器调用相应的执行器来执行数据库操作。
执行结果返回给AI模型。

5. 可扩展性和维护

添加工具：在executors目录下实现新工具，并在__init__.py中注册它们。
环境配置：通过.env文件管理环境变量。
日志记录：使用logger_helper确保一致的日志记录。

6. 部署和执行

6.1 本地执行

# 设置环境
cp .env.example .env
# 根据需要修改.env文件

# 安装依赖
pip install -r requirements.txt

# 运行服务器
python mysql_mcp_server/main.py run

6.2 Docker部署

# 使用Docker Compose启动数据库
docker-compose up -d db
# 使用Docker Compose构建并运行mysql-mcp-server（包括重建）
docker-compose up -d --build mysql-mcp-server

7. 安全考虑

通过环境变量管理数据库凭据。
在生产环境中使用强密码。
考虑在必要时为数据库连接实施SSL/TLS加密。