mysql-mcp-server

一个 Model Context Protocol (MCP) 服务器，允许 MCP 客户端（Claude Desktop、Claude Code 等）通过四个工具对 MySQL 数据库执行 SQL： select、insert、update 和 delete。

该服务器作为 uv 管理的 Python 包运行，并通过 stdio 与客户端通信，作为客户端启动的子进程运行。

环境要求

• Python 3.11+

• uv

• 可访问的 MySQL 服务器

Related MCP server: Universal Database MCP Server

安装

uv sync

配置

服务器需要六个值，每个值都可以通过环境变量和/或 CLI 标志设置 （CLI 标志优先于环境变量）：

如果缺少必需的值，或者 MYSQL_MODE 不是 readonly/readwrite，服务器会 向 stderr 打印错误并以状态码 1 退出，不会启动。

• readonly 模式：只允许 select 工具。insert/update/delete 会被 以 PERMISSION_DENIED 错误拒绝。

• readwrite 模式：允许所有四个工具。

模式在进程生命周期内固定不变；运行时无法更改。

安全建议：readonly 模式是应用层面的防护，不能 替代数据库权限。如有可能，请让 readonly 模式指向一个 仅拥有 SELECT 授权的 MySQL 账户。

是否需要 .env 文件？ 不需要。服务器本身从不读取 .env 文件——它只 读取 CLI 标志和真实的进程环境变量（os.environ）。如何将 值注入该环境取决于你如何运行它：

• 作为 MCP 服务器运行（参见从 MCP 客户端连接）： 客户端（Claude Desktop/Code）会启动服务器进程，并将其自身 JSON 配置中的 env 块直接作为环境变量注入。不涉及也不需要 .env 文件。

• 直接运行 CLI 进行本地开发/测试：.env 只是为了方便 你无需手动 export 六个变量。将 .env.example 复制为 .env，填写 真实值，然后显式加载它——它不会被自动读取：

  uv run --env-file .env mysql-mcp-server

  .env 已被 git 忽略，绝不能提交。

运行

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

从 MCP 客户端连接

Claude Desktop / Claude Code

在 MCP 客户端的服务器配置中添加一个条目（例如 Claude Desktop 的 claude_desktop_config.json，或 Claude Code 的 .mcp.json）：

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

编辑配置后重启客户端。select、insert、update 和 delete 工具（受 MYSQL_MODE 约束）随后即可供模型使用。

工具

所有四个工具都接受 {"query": string, "params"?: array}，并且始终在 query 中使用 %s 参数绑定占位符——绝不要将用户输入以字符串格式化方式拼入查询。

每次工具调用都会返回以下之一：

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

错误码：PERMISSION_DENIED、INVALID_QUERY_TYPE、MULTI_STATEMENT_NOT_ALLOWED、 DB_CONNECTION_ERROR、DB_EXECUTION_ERROR、INTERNAL_ERROR。

多语句查询（以 ; 分隔）以及任何 DDL/权限语句（DROP、 TRUNCATE、ALTER、GRANT、CREATE USER 等）一律被拒绝，因为只有 上述四种白名单语句类型会被接受。

开发

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

故障排查

• 服务器以状态码 1 立即退出：缺少必需的 MYSQL_* 值，或者 MYSQL_MODE 无效——请检查 stderr 以确定具体原因。

• DB_CONNECTION_ERROR：MySQL 无法访问，或凭据错误。服务器 会继续运行，并在下一次工具调用时重试连接。

• 对 insert/update/delete 返回 PERMISSION_DENIED：服务器当前以 readonly 模式运行；如需写入操作，请以 MYSQL_MODE=readwrite 重启。

版本历史

• 0.1.0 — 初始版本：select/insert/update/delete 工具、readonly/ readwrite 模式策略、stdio MCP 传输、连接断开时自动重连并重试。