designcomputer/mysql_mcp_server · 上手攻略

  • 仓库：designcomputer/mysql_mcp_server
  • 链接：https://github.com/designcomputer/mysql_mcp_server
  • 分类：MCP 服务器 / 数据库 / 安全数据访问
  • 作者：spark
  • 更新：2026-08-15

是什么

mysql_mcp_server 是一个 Model Context Protocol (MCP) 服务器，让支持 MCP 协议的 AI 客户端（Claude Desktop、Claude Code、Autohand Code 等）能够以结构化、受控的方式查询、操作 MySQL 数据库。它是用 Python 实现的轻量级服务端，不做 ORM、不替代数据库工具链——只是在 LLM 与 MySQL 之间架一道有审计、有 schema 描述、有安全限制的桥。

支持的传输：

  • STDIO（默认，本地首选）；
  • Streamable HTTP / SSE（MCP_TRANSPORT=sse，远程 / 自托管场景推荐）；
  • 托管：可直接用 Fronteir AI 的托管版本，无需本地启动；
  • 本地一键安装：Smithery 一行命令装到 Claude Desktop。

项目采用 MIT 协议，三方审计可参考 agentaudit.dev/packages/mysql-mcp-server。

解决什么问题

  1. 让 LLM 直连生产数据库时的合规焦虑：传统 "把 DSN 塞给 AI" 路径存在 SQL 注入、越权、敏感字段外泄等多重风险。本项目在工具层做了标识符白名单校验（仅允许字母数字 / 下划线 / $，且仅允许单个 . 作为 db.table 分隔符），并通过 DML destructive 提示与日志中的密码 / 私钥掩码，把责任面收紧到"数据库连接这一段"。
  2. 多数据库模式：省略 MYSQL_DATABASE 时，服务器返回所有用户库（过滤系统库），允许在 SQL 中用 mydb.mytable 跨库访问，避免被一个 schema 绑死。
  3. 远程数据库安全访问：原生支持 SSL/TLS（MYSQL_SSL_MODE 全部四种状态）与 SSH 跳板（MYSQL_SSH_ENABLE=true），无需在客户端机器上开公网端口或直连 MySQL 默认端口。
  4. 审计与可观测性：服务器自带综合日志，可对接审计系统；环境变量集中管理凭据；.env 自动加载。
  5. 配套 prompt 模板：除了工具，还提供 explore_database 与 analyze_table 两个 MCP prompt——在 Claude Code 里是 /mcp__mysql__explore_database slash 命令，在 Claude Desktop 是 prompts (+) 菜单里的工作流入口。

快速安装

1. 直接安装（最简）

pip install mysql-mcp-server

适合个人本地开发，pip 一行解决。

2. Claude Desktop 一键（推荐日常）

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Smithery 自动写到 claude_desktop_config.json。

3. Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

加 --scope project 让注册仅在本 workspace 内可见。

4. 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

5. 手动写到 mcp.json（通用）

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "mysql-mcp-server", "mysql_mcp_server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

需要先装 uv（uvx 子命令）。

6. Claude Desktop 手动配置（claude_desktop_config.json）

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": ["--directory", "path/to/mysql_mcp_server", "run", "mysql_mcp_server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

⚠️ Claude Desktop / Claude Code 启动 MCP 时用的是自己的工作目录，不会找到项目里的 .env。请把 MYSQL_* 写在 MCP 配置的 env 块里，而不是依赖 .env。

核心用法

必需环境变量

MYSQL_HOST=localhost
MYSQL_PORT=3306              # 可省，默认 3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可省——省略即多数据库模式

进阶变量

# SSL
MYSQL_SSL_MODE=DISABLED      # DISABLED / REQUIRED / VERIFY_CA / VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10

# 连接行为
MYSQL_SQL_MODE=TRADITIONAL
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=           # 老 MySQL 可填 mysql_native_password
MYSQL_USE_PURE=false         # 强制纯 Python 连接器
MYSQL_RAISE_ON_WARNINGS=false

# SSE / HTTP 传输
MCP_TRANSPORT=stdio          # stdio 或 sse
MCP_SSE_HOST=0.0.0.0
PORT=8000
MCP_SSE_ALLOWED_HOSTS=       # 逗号分隔 Host 头白名单

# SSH 跳板
MYSQL_SSH_ENABLE=false
MYSQL_SSH_HOST=
MYSQL_SSH_PORT=22
MYSQL_SSH_USER=
MYSQL_SSH_KEY_PATH=
MYSQL_SSH_REMOTE_HOST=localhost
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

服务器启动时通过 python-dotenv 自动从当前工作目录（或上级目录）加载 .env——仅对"自己从项目目录启动"有效。

多数据库模式

不设 MYSQL_DATABASE 时：

  • list_resources 返回所有用户数据库（系统库被过滤）；
  • SQL 中必须使用 mydb.mytable 这种全限定名；
  • ⚠️ 仅支持单条 SQL 语句——USE db; SELECT ... 这种多语句不被允许。

工具一览

execute_sql

  • 参数：query（string）
  • 支持：SELECT / SHOW / DESCRIBE / INSERT / UPDATE / DELETE（DML 操作会被标记 destructive 提示）
  • 限制：仅单语句
  • 跨库：用 database.table

get_schema_info

  • 参数：table_name（可选）
  • 输出：列名 / 类型 / 可空性 / 默认值 / 注释
  • 跨库：传 database.table；裸名落到 MYSQL_DATABASE

get_table_sample

  • 参数：table_name（string），limit（可选，默认 ≤ 20）
  • 用途：快速看数据形态与内容，不必拉全表
  • 跨库：同上

list_resources

枚举当前可访问的表。

标识符校验

get_schema_info / get_table_sample 的表名与库名走白名单——只允许字母数字、下划线、$，且只允许一个 . 做 database.table 分隔。其他特殊字符一律拒绝，从源头阻 SQL 注入。

Prompt（工作流入口）

  • /mcp__mysql__explore_database：发现表 → 取 schema → 抽样 → 给出总结
  • /mcp__mysql__analyze_table <table_name>：深入单个表（含跨库 database.table 写法）

二者都组合了 get_schema_info 与 get_table_sample；前者还会用 resource listing 列举表。

调试

不要直接 python -m mysql_mcp_server。用 MCP Inspector：

pip install -r requirements.txt
# 然后用 MCP Inspector 启动调试

典型适用场景

  • 数据分析师 + LLM 协作：把 LLM 当 SQL 翻译 / 探索伙伴，本地或公司网络内的 MySQL 直连，schema 与抽样让 LLM 写出来的查询更准确。
  • 代码评审 / 自动化运维：CI 中调用 MCP 跑只读 schema 校验或迁移对比（结合 DML destructive 标记守住写权限边界）。
  • 跨内网 MySQL 访问：用 SSH 跳板连远端开发库，LLM 不直接拿到远端凭据。
  • 临时多库探索：不绑死 schema，让 AI 跨库探查表结构；或分阶段从单库切到多库（仅改环境变量）。
  • 自托管 MCP 服务：在 Docker / K8s 中跑 SSE 模式，前面挂 nginx 反代做 Basic Auth（见下）。

坑与注意

  • 不要直接 python -m mysql_mcp_server 跑——会启动失败或行为异常。用 MCP Inspector 或宿主（Claude Desktop 等）启动。
  • Claude Desktop / Code 不读 .env：凭据必须放进 MCP 配置的 env 块。
  • SSE 默认无鉴权：MCP_SSE_HOST=0.0.0.0 + 无认证 = 公网裸奔。必须用反向代理加认证（例：nginx + auth_basic），并把 MCP_SSE_HOST 限回 127.0.0.1、MCP_SSE_ALLOWED_HOSTS 设成反代对外的 Host:Port。
  • MySQL 用户最小权限：禁止用 root。给 LLM 的账号应只授必要的 SELECT/INSERT/UPDATE/DELETE 子集。
  • 多语句查询不支持：USE db; SELECT ... 直接报错；要么拆成两条 query，要么用 database.table 全限定名。
  • DML 操作标记为 destructive：客户端（Claude）会弹出确认，按需启用；不要静默授权 DDL。
  • 标识符白名单：如果你有特殊命名的库 / 表（如带连字符或中文），会被工具层拒绝——这是设计如此，但要在前端提前和模型讲清命名规范，避免反复报错。
  • 跨库语义：list_resources 不返回系统库（mysql / information_schema / performance_schema / sys）；如需这些请直接 SQL 查询（注意权限）。
  • 凭证存放：日志会自动掩码密码与 SSH 私钥，但若把 .env 提交到 git 仍会泄露——加 .env 到 .gitignore。
  • 远程托管：Fronteir AI 托管版有第三方处理数据风险；合规敏感业务请选本地部署。

与同类对比

项目 语言 关键差异
designcomputer/mysql_mcp_server（本项目） Python 极简、强 schema 安全、支持 SSH/SSL、多数据库模式；适合 Python 栈或想"读懂源码后改"的用户
benborla/mcp-server-mysql Node.js + TypeScript 默认只读、可配置 DML；功能更"企业级"（连接池 / 限流）；适合 Node.js 栈或需要更细运维
executeautomation/database-server Node.js 一份代码覆盖 MySQL/PostgreSQL/SQL Server/SQLite；统一抽象但 MySQL 特定优化弱
DBHub Go 一个 server 覆盖多 SQL 引擎，自托管取向
datamcp 托管 服务端凭据 + 多客户端访问；不自托管

按 datamcp 2026 横向评测 的建议路径：架构优先，先想清楚 "Python / Node / 托管" 再选实现。

一句话推荐结论

想要最小可读、最快上手、Python 栈首选的 MySQL MCP 服务器，本项目即答案；只要确保给 MCP 用最小权限账号、SSE 自托管时挂反代鉴权、DML destructive 提示保留在生产路径中。

⚠️ 不确定项 - 当前 PyPI 版本号：本次仅看到 pip install mysql-mcp-server 与 uvx 路径，未抓 pip show mysql-mcp-server 的版本号；建议读者 pip 安装时通过 pip index versions mysql-mcp-server 或 PyPI 页面自查。 - GitHub Stars / Forks 数字：外部索引（Augment Code）显示 698 stars / 162 forks——属第三方的缓存数字，可能与 GitHub 实时数略有出入。 - datamcp / dreamfactory 横向评测的具体发布日期：两个二手来源给出的"2026"时间表述未做独立溯源，仅作并列参考。

来源：仓库 README（GitHub）、tavily web_search（datamcp 2026 评测、DreamFactory 指南、Augment Code MCP Registry）。