mysql-mcp-server

<a href="https://glama.ai/mcp/servers/6y836dz8o5"> <img width="380" height="200" src="https://glama.ai/mcp/servers/6y836dz8o5/badge" /> </a>

한국어 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 帐户用户开放。

工具添加提示

• 添加工具
  • 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 Server 是一个基于 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 分层结构

1. 接口层：MCP 服务器 (FastMCP)
2. 业务逻辑层：处理程序和执行器
3. 数据访问层：数据库连接和查询执行

4.2 关键类和模块

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

4.3 通信流程

1. AI 模型从 MCP 服务器请求可用工具列表。
2. 服务器返回可用工具列表。
3. AI 模型请求执行特定工具。
4. 服务器调用相应的执行器来执行数据库操作。
5. 执行结果返回给 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 加密。