Dify 与 MySQL 深度整合实战：基于 MCP 协议的数据交互

Dify 与 MySQL 深度整合实战：基于 MCP 协议的数据交互

背景与目标

在数字化时代，将大语言模型（LLM）的能力落地到具体业务数据中是开发者的常见需求。Dify 作为一款强大的 LLM 应用开发平台，通过 MCP（Model Context Protocol）协议与 MySQL 数据库结合，能够让我们用自然语言直接查询和分析结构化数据。这种整合不仅降低了 SQL 编写的门槛，还让 AI 具备了处理复杂业务逻辑的能力。

本文将详细介绍如何从零搭建这一环境，包括 Dify 部署、MySQL 表结构初始化、MCP Server 配置以及 Dify 工作流编排，最后通过实际测试验证效果并排查常见问题。

环境准备

1. 基础依赖

确保开发环境已安装 Python 3.8+、Docker 和 Docker Compose。建议使用 Linux 系统（如 Rocky 9.5 或 Ubuntu），以保证兼容性。

2. 安装 Dify

从官方仓库克隆代码并启动服务：

git clone https://github.com/langgenius/dify.git --branch 1.1.0
cd dify/docker
cp .env.example .env
docker compose up -d

若遇到镜像拉取问题，可配置 Docker 代理。在 /etc/systemd/system/docker.service.d/ 下创建 http-proxy.conf 文件，填入代理地址后重启 Docker 服务即可。

启动成功后，访问 http://localhost:3000 进行首次管理员账号设置。

3. 初始化 MySQL 数据库

新建数据库 test，并创建以下表结构。注意 SQL 语句中的空格和关键字规范。

CREATE DATABASE test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE test;

-- 教师表
CREATE TABLE teachers (
    id VARCHAR(255) NOT NULL COMMENT '教师 ID',
    name VARCHAR(255) NOT NULL COMMENT '姓名',
    gender ENUM('男','女') DEFAULT '男',
    subject VARCHAR(255) NOT NULL COMMENT '科目',
    title VARCHAR(255) NOT NULL COMMENT '职称',
    phone VARCHAR(255) NOT NULL,
    office VARCHAR(255) NOT NULL,
    wechat VARCHAR(255),
    isHeadTeacher ENUM('true','false') DEFAULT 'false',
    PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 班级表
CREATE TABLE classes (
    id VARCHAR(255) NOT NULL COMMENT '班级 ID',
    className VARCHAR(255) NOT NULL COMMENT '班级名称',
    grade INT NOT NULL COMMENT '年级',
    headTeacherId VARCHAR(255) NOT NULL COMMENT '班主任 ID',
    classroom VARCHAR(255) NOT NULL COMMENT '教室',
    studentCount INT NOT NULL COMMENT '人数',
    remark VARCHAR(255),
    PRIMARY KEY (id),
    FOREIGN KEY (headTeacherId) REFERENCES teachers(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 学生表
CREATE TABLE students (
    id VARCHAR(255) NOT NULL COMMENT '学号',
    name VARCHAR(255) NOT NULL,
    gender ENUM('男','女') DEFAULT '男',
    birthDate DATETIME NOT NULL,
    classId VARCHAR(255) NOT NULL,
    phone VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    height INT NOT NULL COMMENT '身高 cm',
    weight INT NOT NULL COMMENT '体重 kg',
    healthStatus ENUM('良好','一般','较差') DEFAULT '良好',
    PRIMARY KEY (id),
    FOREIGN KEY (classId) REFERENCES classes(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 课程表
CREATE TABLE courses (
    id VARCHAR(255) NOT NULL COMMENT '课程 ID',
    courseName VARCHAR(255) NOT NULL,
    credit INT NOT NULL,
    teacherId VARCHAR(255) NOT NULL,
    semester VARCHAR(255),
    type ENUM('必修','选修') DEFAULT '选修',
    PRIMARY KEY (id),
    FOREIGN KEY (teacherId) REFERENCES teachers(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 成绩表
CREATE TABLE scores (
    id VARCHAR(255) NOT NULL,
    studentId VARCHAR(255) NOT NULL,
    courseId VARCHAR(255) NOT NULL,
    score INT NOT NULL,
    examDate DATE NOT NULL,
    usualScore INT DEFAULT 0,
    finalScore INT DEFAULT 0,
    PRIMARY KEY (id),
    FOREIGN KEY (studentId) REFERENCES students(id),
    FOREIGN KEY (courseId) REFERENCES courses(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

录入测试数据后，确保各表关联正常。

搭建 MCP Server

我们需要一个中间件来桥接 Dify 和 MySQL。这里使用开源的 mysql_mcp_server_pro。

1. 获取代码

git clone https://github.com/wenb1n-dev/mysql_mcp_server_pro.git
cd mysql_mcp_server_pro

2. 配置环境变量

编辑 .env 文件，填入 MySQL 的连接信息（IP、端口、用户名、密码）。注意不要留多余空格，否则会导致连接失败。

3. 安装依赖

pip install mcp mysql-connector-python uvicorn python-dotenv starlette

4. 启动服务

uv run server.py

服务启动后，默认监听 SSE 接口，等待 Dify 调用。

Dify 工作流配置

1. 安装插件

在 Dify 后台进入「插件管理」，安装以下两个关键插件：

• Agent 策略（支持 MCP 工具）：用于调度 Agent 行为。
• MCP SSE：用于通过 SSE 协议发现并调用外部工具。

插件源码参考 GitHub 仓库，确保版本兼容。

2. 配置 MCP SSE

进入 MCP SSE 插件配置页，填写之前启动的 MCP Server 地址：

{"mysql_mcp_server_pro":{"url":"http://192.168.1.XXX:9000/sse"}}

保存后，Dify 应能识别到 MySQL 相关的工具列表。

3. 创建工作流

1. 选择「Chatflow」类型创建工作流。
2. 删除默认的 LLM 节点，拖入一个「Agent」节点。
3. 在 Agent 配置面板中，选择 ReAct (Support MCP Tools) 策略。经验证，该策略对 MCP 工具的支持比 FunctionCalling 更稳定，能避免找不到 call_tool 方法的问题。
4. 在工具列表中，添加刚才配置的 MCP 服务器工具。
5. 设置提示词（System Prompt），明确告知 Agent 数据库结构及查询规则。例如：

   使用中文回复。当用户提问涉及学生、成绩等实体时，必须使用 MySQL MCP 工具查询。表结构包含 teachers, classes, students, courses, scores。

4. 模型选择建议

本地部署的大模型（如 Deepseek 14B）推理速度较慢，可能影响体验。建议接入云端 API（如阿里百炼云）以获得更快的响应速度和更好的理解能力。

测试与验证

完成配置后，在工作流测试界面输入自然语言问题进行验证：

• 场景一：列出身高大于等于 168cm 的所有学生。
• 场景二：列出体重大于等于 60kg 的学生。
• 场景三：哪个学生成绩最好？
• 场景四：总成绩最好的是哪个班级？

观察 Agent 是否自动转换为正确的 SQL 语句并返回结果。如果输出符合预期，说明整合成功。

常见问题排查

1. 连接失败

若提示'连接超时'或'无法找到服务器'，请检查：

• 防火墙是否开放了 MySQL 端口（默认 3306）。
• MCP SSE 配置中的 IP 地址是否正确，且网络可达。
• MySQL 服务是否正常运行（systemctl status mysql）。

2. 工具调用错误

若提示'找不到工具'，通常是因为：

• 未选择正确的 Agent 策略（务必选 ReAct）。
• MCP SSE 插件未正确授权或地址配置有误。
• 工具列表未刷新，尝试重新保存配置。

3. SQL 执行错误

若返回'语法错误'或'表不存在'：

• 检查提示词中是否准确描述了表结构，特别是字段名和关系。
• 确认数据库中表名是否与提示词一致。
• 优化提示词，增加对变量引用的约束，例如明确指定'使用变量 score 作为查询条件'。

通过以上步骤，你可以构建一个基于 Dify 和 MCP 的智能数据查询应用，实现自然语言驱动的数据分析。