mineru/mcp-mysql

MCP MySQL Server 镜像文档

镜像概述

MCP MySQL Server是基于MCP（Model Context Protocol）的服务器应用，为AI模型提供与MySQL数据库交互的工具，支持数据库操作的执行与结果返回。

核心功能与特性

主要功能

• MCP协议通信接口，实现AI模型与MySQL数据库的交互
• 提供多种数据库操作工具（Executors），包括表创建、结构查询、查询执行计划分析、数据插入与查询等功能
• 分层架构设计，解耦通信、业务逻辑与数据访问层

技术特性

• Python开发，轻量且易于扩展
• Docker容器化部署，确保环境一致性
• 兼容MySQL 8.0，支持utf8mb4字符集与排序规则
• 完善的日志与错误处理机制

系统构成

主要组件

• MCP服务器：基于FastMCP或stdio的通信服务，处理AI模型请求
• MySQL数据库：数据存储核心，支持持久化存储
• 工具执行器（Executors）：实现具体数据库操作的功能模块

技术栈

• 编程语言：Python
• 数据库：MySQL 8.0
• 核心依赖库：
  • mcp：MCP协议实现，支持AI模型通信
  • PyMySQL：MySQL数据库连接与查询执行
  • pandas：数据处理与结果格式化
  • python-dotenv：环境变量管理
  • fire：命令行接口实现

部署环境

• Docker及Docker Compose容器化部署
• 默认端口：8081（MCP服务器）、3306（MySQL数据库）

目录结构

MCPBoilerPlate/
├── mysql_mcp_server/           # 主应用目录
│   ├── executors/              # 数据库操作执行器
│   │   ├── create_table.py     # 表创建工具
│   │   ├── desc_table.py       # 表结构查询工具
│   │   ├── explain.py          # 查询执行计划工具
│   │   ├── insert_query.py     # INSERT查询执行工具
│   │   ├── select_query.py     # SELECT查询执行工具
│   │   └── show_tables.py      # 表列表查询工具
│   ├── handlers/               # MCP请求处理器
│   │   ├── call_tool.py        # 工具调用处理
│   │   └── list_tools.py       # 工具列表提供
│   ├── helper/                 # 工具模块
│   │   ├── db_conn_helper.py   # 数据库连接管理
│   │   ├── logger_helper.py    # 日志工具
│   │   └── tool_decorator.py   # 工具装饰器
│   ├── models/                 # 数据模型
│   └── main.py                 # 应用入口
├── docker-compose.yml          # Docker Compose配置
├── Dockerfile                  # Docker镜像构建配置
├── requirements.txt            # 依赖包列表
└── .env.example                # 环境变量示例

架构设计

分层结构

1. 接口层：MCP服务器（FastMCP或stdio），处理AI模型通信
2. 业务逻辑层：处理器（Handlers）与执行器（Executors），实现核心业务逻辑
3. 数据访问层：数据库连接管理与查询执行，负责数据交互

核心类与模块

• MySQLMCPServer：主服务器类，负责MCP服务器初始化与运行
• DatabaseManager：单例模式数据库连接管理器，统一管理数据库连接
• 执行器模块：
  • execute_create_table：创建数据库表
  • execute_desc_table：查询表结构
  • execute_explain：分析查询执行计划
  • execute_insert_query：执行INSERT语句
  • execute_select_query：执行SELECT语句
  • execute_show_tables：查询数据库表列表

通信流程

1. AI模型向MCP服务器请求工具列表
2. 服务器返回可用工具清单
3. AI模型发送具体工具调用请求（含参数）
4. 服务器调用对应执行器执行数据库操作
5. 执行结果格式化后返回给AI模型

使用方法

Docker Compose部署

配置文件示例

yaml
services:
  mysql-mcp-server:
    image: docker.xuanyuan.run/mineru/mcp-mysql:latest
    ports:
      - 8081:8081
    environment:
      - MYSQL_HOST=localhost
      - MYSQL_PORT=3306
      - MYSQL_USER=root
      - MYSQL_PASSWORD=mcpTest1234!!!
      - MYSQL_DATABASE=mcp_test
      - MCP_PORT=8081
  db:
    image: docker.xuanyuan.run/mysql:8.0.35
    restart: always
    environment:
      - TZ=Asia/Seoul
      - MYSQL_DATABASE=mcp_test
      - MYSQL_ROOT_PASSWORD=mcpTest1234!!!
    volumes:
      - mysql_db:/var/lib/mysql
    ports:
      - 3306:3306
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
volumes:
  mysql_db:

部署步骤

1. 创建docker-compose.yml文件并复制上述配置
2. 执行命令启动服务：docker-compose up -d
3. 查看服务状态：docker-compose ps

环境变量配置

适用场景

• AI模型需要直接操作MySQL数据库的场景
• 通过标准化协议（MCP）实现数据库交互的应用
• 快速部署数据库操作服务的开发与测试环境