mysql-mcp-server

mysql-mcp-server

한국어 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 配置

Cursor 0.46 及更高版本支持 MCP 功能。

此外，只有 Cursor Pro 账号用户才能使用 MCP 功能。

添加工具的提示

• 添加工具
  • execute 函数负责实现实际的逻辑执行（服务层）。
  • @tool 装饰器有助于将工具注册到 MCP（控制器层）。
• 说明
  • mysql_mcp_server/executors 下的每个文件都代表一个工具。
  • 添加新工具时，必须将其导入 mysql_mcp_server/executors/__init__.py，并将其加入 __all__ 数组。
  • 这样可确保该模块自动注册到 TOOLS_DEFINITION 变量中。

flowchart LR;
    A[AI Model] -->|Request tool list| B[MCP Server]
    B -->|Return available tools| A

    A -->|Request specific tool execution| B
    B -->|Call the corresponding executor| C[Executors]
    
    subgraph Executors
        C1[execute_create_table] -->|Create table| D
        C2[execute_desc_table] -->|View table schema| D
        C3[execute_explain] -->|Query execution plan| D
        C4[execute_insert_query] -->|Execute INSERT query| D
        C5[execute_insight_starter] -->|Checking the schema for building reports| D
        C6[execute_invoke_viz_pro] -->|Visualization chart recommendations| D
        C7[execute_select_query] -->|Execute SELECT query| D
        C8[execute_show_tables] -->|Retrieve table list| D
    end

    D[DatabaseManager] -->|Connect to MySQL| E[MySQL 8.0]

    E -->|Return results| D
    D -->|Send results| C
    C -->|Return results| B
    B -->|Return execution results| A

🚧 开发路线图 🚧

• ⚙️ 参数选项

  • 🔧 启用／禁用各项工具的开关：提供降低输入上下文成本的功能 💰
  • 🔒 查询安全级别设置：提供可选控制，限制可能损害资产价值的操作，例如 DROP、DELETE、UPDATE 🚫

• ✨ 功能

  • 📊 数据分析报告生成：提供报告生成功能，优化模型根据用户请求恰当选择各种图表 📈
    • 📝 支持预设格式的报告
    • 🖌️ 丰富报告模板
  • 🗄️ 扩展 Text2SQL 支持
  • 🌐 SSH 连接支持：通过 SSH 实现安全远程访问，以执行高级操作 🔑
  • 📥 文件提取功能
    • 📄 CSV
    • 📑 JSON
    • 📉 Excel

1. 概述

MCP MySQL Server 是一个基于 MCP（Model Context Protocol）的 MySQL 数据库操作服务端应用。此服务提供可让 AI 模型与 MySQL 数据库交互的工具。

2. 系统配置

2.1 关键组件

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

2.2 技术栈

• 语言：Python
• 数据库：MySQL 8.0
• 主要库：
  • mcp：实现用于 AI 通信的 Model Context Protocol
  • PyMySQL：连接 MySQL 并执行查询
  • pandas：处理和分析数据
  • python-dotenv：管理环境变量
  • fire：实现命令行接口

2.3 部署环境

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

3. 目录结构

MCPBoilerPlate/
├── mysql_mcp_server/           # Main application directory
│   ├── executors/              # Database operation executors
│   │   ├── create_table.py     # Tool for creating tables
│   │   ├── desc_table.py       # Tool for viewing table schema
│   │   ├── explain.py          # Tool for query execution plans
│   │   ├── insert_query.py     # Tool for INSERT query execution
│   │   ├── insight_starter.py  # Schema verification tools for write reports
│   │   ├── invoke_viz_pro.py   # Tool for Visualization chart recommendation
│   │   ├── select_query.py     # Tool for SELECT query execution
│   │   └── show_tables.py      # Tool for retrieving table lists
│   ├── helper/                 # Utility modules
│   │   ├── db_conn_helper.py   # Manages database connections
│   │   ├── logger_helper.py    # Logging utilities
│   │   └── tool_decorator.py   # Tool decorator
│   └── main.py                 # Application entry point
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile                  # Docker image build settings
├── requirements.txt            # Dependency package list
└── .env.example                # Example environment variables file

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 本地执行

# Setup environment
cp .env.example .env
# Modify .env file as needed

# Install dependencies
pip install -r requirements.txt

# Run the server
python mysql_mcp_server/main.py run

6.2 Docker 部署

# Start database using Docker Compose
docker-compose up -d db
# Build and run mysql-mcp-server with Docker Compose (including rebuilds)
docker-compose up -d --build mysql-mcp-server

7. 安全注意事项

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