MySQL MCP Server

MySQL MCP 服务

一个 Python Model Context Protocol（MCP）服务，可从兼容 MCP 的客户端检查和查询 MySQL 数据库。它提供表发现、架构检查、只读查询执行、DDL 查询、查询说明，以及可选的写入/DDL 工具，用于受控的数据库管理工作流。

功能

• 列出表并描述表架构
• 在安全检查下执行 SELECT 查询
• 获取 SHOW CREATE TABLE 输出
• 说明查询执行计划
• 汇总表和行数
• 为有意使用更高数据库权限运行的用户提供可选的写入和 DDL 工具

安全模型

mysql_execute_read_query 只接受以 SELECT 开头的单条语句，会拒绝常见的 SQL 修改关键字以及有风险的文件读写形式，并通过 MYSQL_READ_QUERY_LIMIT 限制返回行数。这只是安全防护措施，不能替代数据库权限。请使用专用的只读 MySQL 用户进行安全探索。如果配置的数据库用户拥有相应权限，写入和 DDL 工具可能会修改或销毁数据；请在 MCP 客户端中将它们设置为需手动批准。

要求

• Python 3.11+
• MySQL 5.7+ 或 MySQL 8.0+
• 兼容 MCP 的客户端，例如 Claude Desktop、Cursor、VS Code 或其他 MCP 宿主

安装

发布到 PyPI 后，可像安装标准 Python MCP 包一样安装或运行此服务：

uvx mdev-mysql-mcp-server

从源代码进行本地开发：

git clone https://github.com/musaddiq-dev/mysql-mcp-server.git
cd mysql-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

复制示例环境文件，并更新数据库连接详细信息。

cp .env.example .env

变量	描述	必填	默认值
MYSQL_HOST	MySQL 主机	否	localhost
MYSQL_PORT	MySQL 端口	否	3306
MYSQL_USER	MySQL 用户名	否	root
MYSQL_PASSWORD	MySQL 密码	否	空
MYSQL_DATABASE	MySQL 数据库名称	是	空
MYSQL_POOL_SIZE	连接池大小	否	5
LOG_LEVEL	Python 日志级别	否	INFO
MYSQL_READ_QUERY_LIMIT	只读查询返回的最大行数	否	1000

只读用户示例：

CREATE USER 'mcp_readonly'@'localhost' IDENTIFIED BY 'change-me';
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'localhost';
FLUSH PRIVILEGES;

运行

mdev-mysql-mcp-server

在 PyPI 发布前，从本地检出目录运行：

python -m mysql_mcp_server.server

MCP 客户端配置

对于已发布的安装，建议使用 uvx。使用 stdio 的 MCP 服务只能将协议消息写入 stdout；此服务通过 Python 日志记录将日志写入 stderr。

Claude Desktop / Cursor / Windsurf / Cline

大多数 MCP 客户端都接受这种 mcpServers JSON 结构：

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["mdev-mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_readonly",
        "MYSQL_PASSWORD": "change-me",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

在此仓库中进行本地开发时，请改用已安装的控制台脚本路径：

{
  "mcpServers": {
    "mysql": {
      "command": "/absolute/path/to/mysql-mcp-server/.venv/bin/mdev-mysql-mcp-server",
      "args": [],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_readonly",
        "MYSQL_PASSWORD": "change-me",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Claude Code CLI

claude mcp add mysql \
  --env MYSQL_HOST=localhost \
  --env MYSQL_PORT=3306 \
  --env MYSQL_USER=mcp_readonly \
  --env MYSQL_PASSWORD=change-me \
  --env MYSQL_DATABASE=your_database \
  -- uvx mdev-mysql-mcp-server

VS Code MCP

VS Code 在其 MCP 配置中使用相同的 command/args/env 模型：

{
  "servers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mdev-mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_readonly",
        "MYSQL_PASSWORD": "change-me",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

工具

工具	用途	安全性
mysql_list_tables	列出已配置数据库中的表	只读
mysql_describe_table	显示表的架构	只读
mysql_execute_read_query	执行单条受限的 SELECT 查询	只读防护
mysql_execute_write_query	执行单条 INSERT、UPDATE 或 DELETE 语句	有破坏性
mysql_execute_ddl	执行单条 CREATE、DROP、ALTER 或 TRUNCATE 语句	有破坏性
mysql_get_table_ddl	返回 SHOW CREATE TABLE 输出	只读
mysql_explain_query	对单条查询运行 EXPLAIN	只读
mysql_get_database_summary	返回表列表和行数	只读

冒烟检查

无需数据库即可通过以下命令验证语法：

python -m py_compile src/mysql_mcp_server/server.py

配置数据库后，启动服务并使用 MCP 客户端调用 list_tables。

分发

此服务通过标准的 Python MCP 分发途径发布：

• PyPI 包：mdev-mysql-mcp-server
• MCP Registry 名称：io.github.musaddiq-dev/mysql-mcp-server
• 运行时提示：uvx
• 传输方式：stdio

此 README 顶部的 mcp-name 标记是通过 MCP Registry 所有权验证的必需内容。用户在本地 MCP 客户端配置中应优先使用 uvx mdev-mysql-mcp-server。

安全注意事项

• 不要提交包含凭据的 .env 或 MCP 客户端配置。
• 使用遵循最小权限原则的数据库用户。
• 对 execute_write_query 和 execute_ddl 明确要求手动批准。
• 未添加额外的身份验证和传输安全措施时，不要通过不受信任的网络公开此服务。

许可证

MIT