mcp-server-mysql · 协议与工具集成

MCP Server for MySQL 运行效果

图1：MCP Server for MySQL 在 AI 编码工具中的运行效果演示

背景故事：当 AI 助手"看见"了你的数据库

做过 RAG（检索增强生成）系统的开发者都知道，最让人头疼的环节不是写 Prompt，而是让 AI 真正理解你的数据。传统方式是把数据库表结构截图贴给 AI，让它自己猜字段含义——结果往往是 AI 生成了看似合理但实际报错的 SQL。

mcp-server-mysql 就是来解决这个问题的：它是一个实现了 Model Context Protocol（MCP）的 MySQL 数据库访问服务器，让大语言模型能以编程方式直接"看见"数据库的完整 Schema 结构——表名、字段类型、索引、外键关系——并执行只读 SQL 查询。

这个项目的诞生背景很有意思：作者 Ben Borla 本身是一名数据库开发者，在工作中频繁需要让 AI 助手帮助分析 MySQL 数据库，但他发现现有的 AI 数据库工具要么权限过大（可以写数据），要么根本无法理解复杂 Schema。于是他决定自己动手，基于 Anthropic 提出的 MCP 协议开发了这个桥接工具，并获得了 Claude Code 官方的优化适配。

类比解释：AI 与数据库之间的"翻译官"

如果把 AI 助手比作一个只会说英语的外国人，把 MySQL 数据库比作一个中文图书馆，那么 mcp-server-mysql 就是那个同声传译员。

它不是简单地把中文书名翻译成英文，而是：

主动介绍图书馆的布局（数据库有哪些表、每张表有几条数据、字段叫什么名字）
帮你查书时判断权限（这是只读账号，不能涂改书籍）
翻译你的查询请求（把你的英文问题转成 SQL，再把结果翻译回英文）
质检翻译质量（用 node-sql-parser 校验生成的 SQL 语法是否正确）

这套机制之所以比直接给 AI 开数据库账号安全得多，是因为 MCP 协议在传输层做了严格隔离——AI 拿到的永远只是"图书馆的目录"，而不是"图书馆的钥匙"。

核心功能：从 Schema 窥探到安全查询

1. 自动 Schema 探测

当 AI 工具（如 Claude Code、Cursor、Windsurf）连接 MCP 服务器后，服务器会自动调用 MySQL 的 information_schema 表，整理出所有数据库的完整结构信息：

数据库级别：列出所有 schema/database，并标注哪些 schema 允许 INSERT/UPDATE/DELETE/DDL 操作
表级别：表名、行数、数据大小、索引大小、创建时间和更新时间
字段级别：每个字段的名称、MySQL 数据类型（VARCHAR、INT、DATETIME 等）

这些信息以结构化 JSON 格式返回给 AI，AI 第一次"看到"数据库时就能准确写出 JOIN 语法，而不用靠猜。

2. 读写权限精细化控制

这是 mcp-server-mysql 区别于其他数据库 MCP 工具的关键设计。传统的数据库访问往往是"全开"或"全关"，但这个项目支持多层级权限配置：

# 全局开关（默认允许读，禁止写）
ALLOW_INSERT_OPERATION=true
ALLOW_UPDATE_OPERATION=true
ALLOW_DELETE_OPERATION=false
ALLOW_DDL_OPERATION=false

# 按 schema 精细化（覆盖全局）
SCHEMA_INSERT_PERMISSIONS={"app_db": true, "analytics": false}

多数据库模式下（MULTI_DB_MODE=true），系统甚至会强制只读，除非显式设置 MULTI_DB_WRITE_MODE=true。这是一个针对生产环境的安全护栏。

3. SQL 语法预校验

集成 node-sql-parser 库，在执行 SQL 前先解析 AST，校验语法正确性。如果 AI 生成了 MySQL 不支持的语法，服务器会提前拦截并返回有意义的错误信息，而不是让 AI 在数据库上"盲试"。

4. 多数据库与连接管理

多数据库模式：一个 MCP 服务器同时代理多个 MySQL 实例
Unix Socket 连接：支持本地 MySQL 通过 /var/run/mysqld/mysqld.sock 连接
SSL/TLS 支持：支持自定义 CA/客户端证书，用于加密连接云数据库

5. Smithery.ai 一键安装

项目接入了 Smithery.ai 的 MCP 注册表，用户只需一条命令即可完成安装配置：

npx @smithery/cli install @benborla29/mcp-server-mysql

技术架构：TypeScript + MCP SDK 的经典组合

从源码来看，这个项目的架构非常清晰，采用标准的 MCP 服务器模式。入口文件 index.ts 注册各类 MCP handlers（tool/resource/prompt），将请求分发到对应的模块处理：

AI 工具 (Claude Code / Cursor 等)
        │  MCP 协议 (stdio / HTTP)
@modelcontextprotocol/sdk v1.15.1  ← 核心 SDK，处理协议握手、消息路由
        │
   src/index.ts (入口)
        │
  ┌─────┼─────┐
src/config  src/db  src/types
(配置解析)  (mysql2)  (类型定义)

依赖栈解读：

依赖	版本	作用
@modelcontextprotocol/sdk	1.15.1	MCP 协议实现（核心）
mysql2/promise	3.14.1	MySQL 驱动，支持连接池和 Promise API
node-sql-parser	5.3.9	SQL AST 解析与语法校验
zod	3.25.67	运行时类型校验
express	5.1.0	提供 HTTP 远程 MCP 模式
@ai-sdk/openai	1.3.22	Claude Code 优化版，支持远程推理
mcp-evals	1.0.18	MCP 工具评测框架

TypeScript 配置使用 ESNext 模块系统和 NodeNext 解析策略，输出 ES2022，对 Node.js 18+ 的原生 ESM 支持良好。

部署方式：Docker 一键启动，无需额外依赖

方式一：Docker（推荐）

Dockerfile 采用多阶段构建：构建阶段用完整工具链编译 TypeScript，生产阶段仅复制 dist/ 和必要文件，最终镜像基于 node:22-alpine，体积控制在 200MB 以内。

# 构建镜像
docker build -t mcp-server-mysql .

# 运行
docker run -e MYSQL_HOST=your-host \
           -e MYSQL_PORT=3306 \
           -e MYSQL_USER=your-user \
           -e MYSQL_PASS=your-password \
           -e MYSQL_DB=your-database \
           mcp-server-mysql

方式二：Smithery.ai 一键安装

npx @smithery/cli install @benborla29/mcp-server-mysql

方式三：本地源码运行

git clone https://github.com/benborla/mcp-server-mysql
cd mcp-server-mysql
npm install -g pnpm && pnpm install
pnpm run build
node dist/index.js

硬件需求极低：无 GPU 需求，运行时仅需 256MB RAM 和 100MB 磁盘空间。

局限与争议：不完美但诚实的评估

1. "只读"是配置层面的，不是数据库层面的

严格来说，项目通过环境变量控制权限，而不是在数据库账号层面做限制。如果 MySQL 账号本身有写权限，而环境变量配置错误，数据仍可能被写入。生产环境建议配合只读数据库账号使用。

2. 缺乏 Web UI

整个项目没有 Web 管理界面，所有配置通过环境变量完成。对于不熟悉命令行的用户，初始配置有一定门槛。

3. 大型数据库的性能问题

当数据库 Schema 非常庞大（上百张表、上千个字段）时，Schema 探测阶段会生成大量 information_schema 查询，可能对生产数据库造成负载。建议在独立的只读副本上运行。

4. 仅支持 MySQL

项目目前仅支持 MySQL/MariaDB。对于 PostgreSQL、MongoDB 等其他数据库，需要寻找对应的 MCP 服务器，无法一个 MCP 服务器通吃。

行业意义：MCP 协议生态的重要基础设施

mcp-server-mysql 的价值不仅在于它本身，而在于它代表了 MCP 协议生态的快速成熟。

自 2024 年底 Anthropic 发布 MCP 协议以来，社区已经围绕它构建了覆盖数据库、文件系统、API 调用、搜索等场景的 MCP 服务器矩阵。mcp-server-mysql 作为数据库类别的典型代表，获得了 1800+ GitHub Stars 和 40 个 open issues，说明社区活跃度很高。

更重要的是，它证明了 MCP 协议能够有效解决 AI "幻觉"问题：当 AI 能够直接查询真实数据库 Schema 时，它生成的 SQL 准确率大幅提升。这对于构建 AI-native 应用（尤其是需要频繁与数据库交互的 SaaS 产品）具有重要参考价值。

增长趋势方面，该项目近期的 growth_trend_score 达到 82.53，属于高增长项目，反映了 AI+数据库赛道持续升温。

MCP Server for MySQL 运行效果

图1：MCP Server for MySQL 在 AI 编码工具中的运行效果演示

背景故事：当 AI 助手"看见"了你的数据库

类比解释：AI 与数据库之间的"翻译官"

如果把 AI 助手比作一个只会说英语的外国人，把 MySQL 数据库比作一个中文图书馆，那么 mcp-server-mysql 就是那个同声传译员。

它不是简单地把中文书名翻译成英文，而是：

主动介绍图书馆的布局（数据库有哪些表、每张表有几条数据、字段叫什么名字）
帮你查书时判断权限（这是只读账号，不能涂改书籍）
翻译你的查询请求（把你的英文问题转成 SQL，再把结果翻译回英文）
质检翻译质量（用 node-sql-parser 校验生成的 SQL 语法是否正确）

核心功能：从 Schema 窥探到安全查询

1. 自动 Schema 探测

当 AI 工具（如 Claude Code、Cursor、Windsurf）连接 MCP 服务器后，服务器会自动调用 MySQL 的 information_schema 表，整理出所有数据库的完整结构信息：

数据库级别：列出所有 schema/database，并标注哪些 schema 允许 INSERT/UPDATE/DELETE/DDL 操作
表级别：表名、行数、数据大小、索引大小、创建时间和更新时间
字段级别：每个字段的名称、MySQL 数据类型（VARCHAR、INT、DATETIME 等）

这些信息以结构化 JSON 格式返回给 AI，AI 第一次"看到"数据库时就能准确写出 JOIN 语法，而不用靠猜。

2. 读写权限精细化控制

这是 mcp-server-mysql 区别于其他数据库 MCP 工具的关键设计。传统的数据库访问往往是"全开"或"全关"，但这个项目支持多层级权限配置：

# 全局开关（默认允许读，禁止写）
ALLOW_INSERT_OPERATION=true
ALLOW_UPDATE_OPERATION=true
ALLOW_DELETE_OPERATION=false
ALLOW_DDL_OPERATION=false

# 按 schema 精细化（覆盖全局）
SCHEMA_INSERT_PERMISSIONS={"app_db": true, "analytics": false}

多数据库模式下（MULTI_DB_MODE=true），系统甚至会强制只读，除非显式设置 MULTI_DB_WRITE_MODE=true。这是一个针对生产环境的安全护栏。

3. SQL 语法预校验

4. 多数据库与连接管理

多数据库模式：一个 MCP 服务器同时代理多个 MySQL 实例
Unix Socket 连接：支持本地 MySQL 通过 /var/run/mysqld/mysqld.sock 连接
SSL/TLS 支持：支持自定义 CA/客户端证书，用于加密连接云数据库

5. Smithery.ai 一键安装

项目接入了 Smithery.ai 的 MCP 注册表，用户只需一条命令即可完成安装配置：

npx @smithery/cli install @benborla29/mcp-server-mysql

技术架构：TypeScript + MCP SDK 的经典组合

AI 工具 (Claude Code / Cursor 等)
        │  MCP 协议 (stdio / HTTP)
@modelcontextprotocol/sdk v1.15.1  ← 核心 SDK，处理协议握手、消息路由
        │
   src/index.ts (入口)
        │
  ┌─────┼─────┐
src/config  src/db  src/types
(配置解析)  (mysql2)  (类型定义)

依赖栈解读：

依赖	版本	作用
@modelcontextprotocol/sdk	1.15.1	MCP 协议实现（核心）
mysql2/promise	3.14.1	MySQL 驱动，支持连接池和 Promise API
node-sql-parser	5.3.9	SQL AST 解析与语法校验
zod	3.25.67	运行时类型校验
express	5.1.0	提供 HTTP 远程 MCP 模式
@ai-sdk/openai	1.3.22	Claude Code 优化版，支持远程推理
mcp-evals	1.0.18	MCP 工具评测框架

TypeScript 配置使用 ESNext 模块系统和 NodeNext 解析策略，输出 ES2022，对 Node.js 18+ 的原生 ESM 支持良好。

部署方式：Docker 一键启动，无需额外依赖

方式一：Docker（推荐）

# 构建镜像
docker build -t mcp-server-mysql .

# 运行
docker run -e MYSQL_HOST=your-host \
           -e MYSQL_PORT=3306 \
           -e MYSQL_USER=your-user \
           -e MYSQL_PASS=your-password \
           -e MYSQL_DB=your-database \
           mcp-server-mysql

方式二：Smithery.ai 一键安装

npx @smithery/cli install @benborla29/mcp-server-mysql

方式三：本地源码运行

git clone https://github.com/benborla/mcp-server-mysql
cd mcp-server-mysql
npm install -g pnpm && pnpm install
pnpm run build
node dist/index.js

硬件需求极低：无 GPU 需求，运行时仅需 256MB RAM 和 100MB 磁盘空间。

局限与争议：不完美但诚实的评估

1. "只读"是配置层面的，不是数据库层面的

2. 缺乏 Web UI

整个项目没有 Web 管理界面，所有配置通过环境变量完成。对于不熟悉命令行的用户，初始配置有一定门槛。

3. 大型数据库的性能问题

4. 仅支持 MySQL

项目目前仅支持 MySQL/MariaDB。对于 PostgreSQL、MongoDB 等其他数据库，需要寻找对应的 MCP 服务器，无法一个 MCP 服务器通吃。

行业意义：MCP 协议生态的重要基础设施

mcp-server-mysql 的价值不仅在于它本身，而在于它代表了 MCP 协议生态的快速成熟。

增长趋势方面，该项目近期的 growth_trend_score 达到 82.53，属于高增长项目，反映了 AI+数据库赛道持续升温。