Production Safe Mysql Mcp Server

mysql-mcp

一个 Model Context Protocol（MCP）服务，让 AI Agent 能够直接访问 MySQL 数据库。

功能

数据查询与修改

• execute_query — 执行 SELECT、INSERT、UPDATE 或 DELETE 语句，并支持参数化查询（? 占位符）
• execute_transaction — 将多条语句作为一个原子批次执行；如果任何语句执行失败，整个事务会自动回滚

架构管理

• create_table — 创建新表
• alter_table — 添加/删除列、重命名列、添加索引等
• drop_table — 删除表（需要设置 ALLOW_DESTRUCTIVE_DDL=true）
• show_tables — 列出数据库中的所有表
• describe_table — 显示表的列结构

数据库管理

• list_databases — 列出所有用户数据库（不包括系统数据库）
• create_database — 创建新数据库，可选择字符集和排序规则
• drop_database — 删除数据库（需要设置 ALLOW_DESTRUCTIVE_DDL=true）

信息查询

• ping — 检查 MySQL 连接状态
• show_columns — 显示表的详细列信息
• get_server_info — 返回 MySQL 版本、字符集和排序规则（只读）

多数据库支持

每个工具都接受 database 参数。无需额外配置，即可在同一会话中查询不同数据库。

---

不支持的功能

以下操作会被安全过滤器永久拦截，在任何情况下都无法绕过：

类别	被拦截的命令
MySQL 设置	SET GLOBAL、SET @@global.*、SET @@SESSION.sql_mode
用户管理	CREATE USER、DROP USER、ALTER USER、RENAME USER
权限管理	GRANT、REVOKE
系统命令	FLUSH、KILL、SHUTDOWN
复制	RESET MASTER/REPLICA、START/STOP SLAVE/REPLICA、CHANGE MASTER
文件访问	LOAD DATA INFILE、SELECT INTO OUTFILE/DUMPFILE
插件	INSTALL PLUGIN、UNINSTALL PLUGIN

其他限制：

• 单次调用中不允许使用 ; 分隔多条语句——请改用 execute_transaction
• drop_table 和 drop_database 默认禁用，除非设置 ALLOW_DESTRUCTIVE_DDL=true，否则会返回错误
• 查询结果最多返回 MAX_ROWS 行（默认值：1000）；对于大型表，请添加 LIMIT 子句

---

安装

**要求：**Node.js 20+

git clone https://github.com/turkeryildirim/mysql-mcp
cd mysql-mcp
npm install
npm run build

复制环境变量示例文件并填写凭据：

cp .env.example .env

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=mcp_user
MYSQL_PASSWORD=your_password

# Optional
MYSQL_DATABASE=default_db
MYSQL_POOL_SIZE=10
MAX_ROWS=1000
ALLOW_DESTRUCTIVE_DDL=false

创建专用 MySQL 用户（推荐）

为 MCP 服务创建一个遵循最小权限原则的 MySQL 用户：

CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX
  ON *.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;

请勿授予 SUPER、FILE、RELOAD 或 GRANT OPTION 权限。

---

Claude Desktop 集成

打开 Claude Desktop 配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

在 mcpServers 下添加以下内容：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "",
        "MAX_ROWS": "1000",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

重启 Claude Desktop。你应该会在工具面板中看到名为 mysql 的服务。

---

Claude CLI 集成

选项 1：.mcp.json — 项目级配置（推荐）

在项目根目录中创建 .mcp.json 文件：

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

每当你从该目录运行 claude 时，服务都会自动加载。

选项 2：全局配置

claude mcp add mysql -- node /absolute/path/to/mysql-mcp/dist/index.js

添加环境变量：

claude mcp add mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_USER=mcp_user \
  -e MYSQL_PASSWORD=your_password \
  -- node /absolute/path/to/mysql-mcp/dist/index.js

验证配置：

claude mcp list
claude mcp get mysql

---

示例提示词

连接后，你可以用自然语言向 Agent 下达指令：

Show me the structure of the users table in testdb
Fetch the last 10 orders from testdb.orders
Create a products table in testdb with id, name, price, and stock columns
Run the following two INSERTs as a single transaction: ...

---

开发

npm run dev        # Watch mode (rebuilds on change)
npm test           # Unit tests (no MySQL connection required)
npm run build      # Production build → dist/