easy-mysql-mcp

一个轻量级的 模型上下文协议 (MCP) 服务器，允许 AI 助手通过安全、结构化的工具接口检查和查询 MySQL 数据库。

本项目使用 Node.js、TypeScript、官方 MCP SDK 和 mysql2/promise。它通过 stdio 运行，因此可以直接被 Claude Desktop 等 MCP 客户端使用。

特性

• 由 mysql2/promise 提供支持的 MySQL 连接池

• 用于数据检索的只读查询工具

• 用于数据修改语句的执行工具

• 用于表、视图、索引和触发器的架构发现工具

• 使用 EXPLAIN 进行查询计划检查

• 当前用户和权限检查

• stdout 保护，防止非 MCP 日志污染 stdio 协议

要求

• Node.js 18 或更高版本

• npm

• 一个可访问的 MySQL 兼容数据库

安装

使用 npx 直接运行服务器：

npx -y easy-mysql-mcp

克隆仓库后进行本地开发：

cd easy-mysql-mcp
npm install
npm run build

配置

使用环境变量配置服务器。你可以通过 MCP 客户端配置提供它们，或者创建一个本地 .env 文件。

.env 示例：

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

使用方法

配置你的 MCP 客户端通过 npx 启动该包。

对于本地开发，请先构建 TypeScript 源码：

npm run build

启动 MCP 服务器：

npm start

服务器通过 stdio 进行通信，通常由 MCP 客户端启动，而不是手动运行。

Claude Desktop 示例

将服务器添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "easy-mysql-mcp": {
      "command": "npx",
      "args": ["-y", "easy-mysql-mcp"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

更新配置后重启 Claude Desktop。

可用工具

安全说明

• 使用具有助手所需最小权限的专用 MySQL 用户。

• 如果只需要检查和报告，请优先使用只读数据库凭据。

• 使用 mysql_execute 时要小心，因为它可能会修改数据。

• 不要将 .env 文件或真实的数据库凭据提交到 GitHub。

• 在对生产数据运行生成的 SQL 之前，请务必进行审查。

开发

npm run dev

这将在监视模式下运行 TypeScript。

要创建生产构建：

npm run build

项目结构

src/
  db.ts       MySQL pool and query helpers
  index.ts    MCP server and tool registration
  proxy.ts    stdout protection for stdio-based MCP transport

许可证

ISC