mysql_mcp_server：让 Claude 这类客户端安全地读 MySQL

它填补的是客户端与数据库之间的那段空白

MCP 客户端能调用工具，但它自己不会连数据库。没有中间层的话，要么把连接串和凭据直接塞给模型，要么让模型生成 SQL 再由人手工执行。mysql_mcp_server 走的是第三条路：进程自己持有凭据，对外只暴露固定几个工具和资源。README 把它描述为「making database exploration and analysis safer and more structured through a controlled interface」，这个 controlled interface 是理解整个项目的关键。

目标用户写得很清楚。安装方式里同时给出了 Claude Code CLI、Claude Desktop 的 Smithery 安装、以及 Autohand Code CLI 三种注册命令，说明作者假设使用者是已经在用某个 MCP 客户端的工程师，而不是要自己写客户端的人。如果你只是想在脚本里跑几条 SQL，psycopg 或 mysql-connector 这类库更直接，没必要引入 MCP 这一层协议开销。

三个工具加一个资源列表，边界画得很窄

服务器对外暴露的能力可以数得清。execute_sql 接受一个 query 字符串，支持 SELECT、SHOW、DESCRIBE 以及 INSERT、UPDATE、DELETE 这类 DML，README 说 DML 操作会被标记 destructive hint。get_schema_info 接受可选的 table_name，返回列名、类型、是否可空、默认值和注释。get_table_sample 接受 table_name 和一个上限 20 的 limit，用来在不拉大结果集的前提下看清数据格式。此外还有 list_resources，把可用的表列成 MCP 资源。

这里有个设计取舍值得点出来。get_table_sample 的 limit 硬性封顶 20，对判断字段格式够用，对做数据分布分析远远不够。而 execute_sql 没有类似的封顶，一条 SELECT 可以返回任意大的结果集。也就是说，防止拉爆上下文的限制只加在了采样工具上，主查询通道是敞开的。

标识符校验的规则也值得一提：get_schema_info 和 get_table_sample 要求名称只含字母数字、下划线和 $，点号只能用作库名与表名之间的分隔符。这条规则挡住了通过表名注入的路径，但它只作用于这两个工具，execute_sql 走的是另一条路。

单库与多库是两套行为，切换靠一个环境变量

MYSQL_DATABASE 设不设，服务器的行为会变。设了，就是单库模式，裸表名默认落在该库。不设，进入多库模式：list_resources 返回所有用户库（系统库被过滤掉），查询表时必须写 mydb.mytable 这种全限定名。get_schema_info 和 get_table_sample 都接受 database.table 形式，裸名则回落到配置的库。

多库模式有一条硬限制，README 用加粗写明：只支持单条 SQL 语句，像 USE db; SELECT ... 这种多语句查询不支持。这条限制贯穿整个 execute_sql 工具，不只是多库模式的问题。对习惯了在 mysql 客户端里连着敲几条语句的人来说，这是个需要改习惯的地方。

连接层还有几个开关。MYSQL_SQL_MODE 默认是 TRADITIONAL，这个模式比 MySQL 自身的默认严格，某些在宽松模式下能过的语句会被拒。MYSQL_RAISE_ON_WARNINGS 默认 false，也就是警告不会中断执行。MYSQL_USE_PURE 可以强制走纯 Python 连接器，MYSQL_AUTH_PLUGIN 用来应付老版本 MySQL 的 mysql_native_password。字符集和排序规则分别由 MYSQL_CHARSET 和 MYSQL_COLLATION 控制，默认 utf8mb4 和 utf8mb4_unicode_ci。

把服务器跑起来：三条注册路径和一堆环境变量

最省事的安装是 pip：pip install mysql-mcp-server。但 README 里更常见的是让客户端自己拉起进程，比如 Claude Code CLI 的命令是 claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server。Autohand Code CLI 的形式略有不同，环境变量直接写在命令里：autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server，后面可以加 --scope project 把注册限制在当前工作区。

必填的只有 MYSQL_HOST、MYSQL_USER、MYSQL_PASSWORD 三项，MYSQL_PORT 不填默认 3306。

关于 .env，README 里那段提示是全文最实用的一段。服务器启动时会用 python-dotenv 从进程工作目录及其父目录加载 .env，所以你自己在项目目录里手动跑时，cp .env.example .env 然后填凭据就能工作。但 Claude Code 和 Claude Desktop 是从它们自己的工作目录启动这个进程的，项目的 .env 找不到，结果就是 Missing required database configuration 这个报错。解决办法是把 MYSQL_* 写进 MCP 配置的 env 块，而不是依赖 .env 文件。很多人第一次配会卡在这里。

远程部署走另一条路。MCP_TRANSPORT 从 stdio 改成 sse 就切到 Streamable HTTP 模式，README 说远程和自托管场景推荐这个模式。此时 MCP_SSE_HOST 通常设成 0.0.0.0 以便在 Docker 或托管环境里监听，端口由 PORT 或 MCP_SSE_PORT 决定，默认 8000。MCP_SSE_ALLOWED_HOSTS 是逗号分隔的 Host 头白名单，默认只允许 localhost:{port} 和 127.0.0.1:{port}，改监听地址时这个也要一起调，否则请求会被挡。

还有一条 SSH 隧道通道。MYSQL_SSH_ENABLE 设为 true 后，MYSQL_SSH_HOST、MYSQL_SSH_PORT（默认 22）、MYSQL_SSH_USER、MYSQL_SSH_KEY_PATH 描述跳板机，MYSQL_SSH_REMOTE_HOST 和 MYSQL_SSH_REMOTE_PORT 描述从跳板机视角看的目标库，本地端口由 MYSQL_LOCAL_PORT 指定（示例值是 3330）。这套配置适合数据库不直接对外暴露的场景。

execute_sql 是这个项目最需要想清楚的地方

README 的措辞是 execute_sql 支持 DML 操作，并且这些操作会被标记 destructive hint。除此之外，材料里没有任何关于只读账号、语句白名单、权限分级或者确认流程的描述。也就是说，防护主要靠两件事：一是你给这个服务器配的 MySQL 账号本身的权限，二是客户端对 destructive hint 的处理方式。

这两件事都不在这个项目的控制范围内。用只读账号是最直接的做法，但那样 execute_sql 的 DML 能力就等于废掉了，工具描述里承诺的 INSERT、UPDATE、DELETE 都用不了。想保留写能力，就得接受模型生成的语句可能直接落到库上。这是一个必须由使用方自己做的判断，项目本身没有提供中间档位。

另一个常被忽略的点是结果集大小。get_table_sample 封顶 20 行，execute_sql 没有对应限制。让模型写一条没有 LIMIT 的查询，返回几十万行，上下文会被直接填满。README 没有提到任何行数或字节数的截断机制。

和直接写一个数据库工具相比，差在哪里

最接近的替代方案不是另一个 MCP 服务器，而是自己写一个 MCP 工具，内部用 SQLAlchemy 或 mysql-connector-python 连接数据库。两者的差别在于抽象层次：自己写的版本可以把查询限制在预先定义好的几个视图上，或者强制注入 LIMIT，或者按表做权限区分。mysql_mcp_server 提供的是一个通用执行入口，灵活性换来的是更粗的管控粒度。

如果需求是「让模型查几张固定的报表」，自建工具更合适，因为你可以把可查询的范围写死在代码里。如果需求是「让模型自由探索一个不熟悉的库」，这个项目的 get_schema_info 加 get_table_sample 组合确实省事，不用自己写元数据查询和采样逻辑。

传输方式上的选择也构成一种对比。STDIO 模式下服务器是客户端拉起的子进程，凭据通过 env 传递，进程生命周期跟着客户端走。SSE 模式下服务器是常驻的 HTTP 服务，可以给多个客户端共用，但此时 MCP_SSE_ALLOWED_HOSTS 这类配置就变成了实际的攻击面控制项，默认值只覆盖本机地址，是有意为之的保守设定。

维护节奏、许可与需要自己确认的部分

项目采用 MIT 许可，这对商用和二次修改都比较宽松，具体条款以仓库里的 LICENSE 文件为准，这里不做法律层面的解读。版本节奏上，v0.4.2 到 v0.4.3 之间隔了约五周，v0.4.3 到 v0.4.4 是同一天内的两次发布，最后一次推送时间在 2026 年 8 月初。仓库未归档，说明仍在维护。

升级成本主要来自环境变量的行为变化。MYSQL_SQL_MODE 的默认值、MYSQL_SSH_* 这一组键、以及 SSE 相关的 MCP_SSE_ALLOWED_HOSTS，都是会直接影响连通性的配置项，跨版本升级时值得对着 README 重新核一遍自己写进 MCP 配置的 env 块。

有一点材料没有覆盖：README 里提到的 Available Prompts 一节被截断了，只看到 explore_databa 开头的表格，完整提示词列表和参数无法从现有材料确认。如果你打算依赖这些斜杠命令，需要自己去仓库里看完整文档。

至于项目主页 designcomputer.com 和 README 里出现的 Fronteir AI 托管选项，材料只给出了链接，没有说明托管方的数据留存策略或凭据处理方式。走托管路线的话，这部分需要单独确认。

编辑结论

如果你已经在用 Claude Code、Claude Desktop 或其他 MCP 客户端，并且需要让模型读取 MySQL 的表结构和少量样本数据来做分析，这个项目可以直接用 uvx 或 pip 装起来，把 MYSQL_* 变量写进 MCP 配置的 env 块即可。不要把它当作生产环境的写入口：execute_sql 能执行 DML，README 只是说明这些操作会带上 destructive 提示，并没有提到任何权限分级或语句白名单。上手前先确认三件事：你的客户端是否从自己的目录启动进程（这决定 .env 会不会被读到）、你的 MySQL 版本是否需要设置 MYSQL_AUTH_PLUGIN、以及 MYSQL_SQL_MODE 默认的 TRADITIONAL 会不会挡掉你依赖的语句。

官方来源

1. designcomputer/mysql_mcp_server on GitHub
2. License: MIT
3. Project website
4. README
5. Releases