mysql-mcp

README

MySQL MCP Server

一个基于 Model Context Protocol (MCP) 的 MySQL 数据库查询工具。该工具允许通过 MCP 协议执行 MySQL 数据库查询和操作。

功能特性

• 支持多种SQL语句：
  • 查询语句：SELECT、SHOW、DESCRIBE/DESC、EXPLAIN
  • 数据操作：INSERT、UPDATE、DELETE
  • 结构操作：CREATE、ALTER、DROP等DDL语句
• 自动处理连接参数：通过环境变量配置数据库连接信息
• 详细错误反馈：提供清晰的错误信息和执行状态
• 智能结果处理：自动识别查询类型，返回相应的结果格式

安装和构建

前置要求

• Go 1.23 或更高版本
• MySQL 数据库服务器

构建

go build -o mysql-mcp

使用方法

工具参数

mysql_query 工具接受以下参数：

参数	类型	必需	描述
database	string	是	MySQL 数据库名称
sql	string	是	要执行的 SQL 语句

环境变量配置

MySQL 连接参数通过环境变量配置：

环境变量	默认值	描述
MYSQL_HOST	localhost	MySQL 服务器主机地址
MYSQL_PORT	3306	MySQL 服务器端口
MYSQL_USERNAME	root	MySQL 用户名
MYSQL_PASSWORD	""	MySQL 密码

示例用法

环境变量设置示例

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USERNAME=myuser
export MYSQL_PASSWORD=mypassword

SELECT 查询示例

{
  "name": "mysql_query",
  "arguments": {
    "database": "testdb",
    "sql": "SELECT id, name, email FROM users WHERE age > 18 LIMIT 10"
  }
}

SHOW 语句示例

{
  "name": "mysql_query",
  "arguments": {
    "database": "allvoice_cn",
    "sql": "SHOW TABLES"
  }
}

返回结果：

{
  "columns": ["id", "name", "email"],
  "rows": [
    {"id": 1, "name": "张三", "email": "zhangsan@example.com"},
    {"id": 2, "name": "李四", "email": "lisi@example.com"}
  ],
  "message": "Query executed successfully. Returned 2 rows."
}

INSERT 语句示例

{
  "name": "mysql_query",
  "arguments": {
    "database": "testdb",
    "sql": "INSERT INTO users (name, email, age) VALUES ('王五', 'wangwu@example.com', 25)"
  }
}

返回结果：

{
  "message": "Statement executed successfully. Rows affected: 1, Last insert ID: 3"
}

UPDATE 语句示例

{
  "name": "mysql_query",
  "arguments": {
    "database": "testdb",
    "sql": "UPDATE users SET age = 26 WHERE name = '王五'"
  }
}

返回结果：

{
  "message": "Statement executed successfully. Rows affected: 1"
}

创建表示例

{
  "name": "mysql_query",
  "arguments": {
    "database": "testdb",
    "sql": "CREATE TABLE products (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100), price DECIMAL(10,2))"
  }
}

错误处理

当发生错误时，工具会返回包含错误信息的 JSON：

{
  "error": "Query execution failed: Table 'testdb.nonexistent' doesn't exist"
}

常见错误类型：

• 连接失败：数据库服务器不可达或认证失败
• SQL 语法错误：SQL 语句格式不正确
• 权限错误：用户没有执行特定操作的权限
• 数据库或表不存在

安全注意事项

1. 避免 SQL 注入：虽然工具本身不提供参数化查询的直接支持，但建议在应用层面进行适当的输入验证和清理。

2. 权限控制：建议为 MCP 工具创建专用的 MySQL 用户，并只授予必要的权限。

3. 密码安全：密码通过环境变量 MYSQL_PASSWORD 配置，避免在代码或配置文件中明文存储。在生产环境中，建议使用更安全的密码管理方案，如 Docker secrets 或 Kubernetes secrets。

4. 网络安全：在生产环境中，确保 MySQL 连接使用 SSL/TLS 加密。

开发和扩展

项目结构

mysql-mcp/
├── main.go          # 主程序文件
├── go.mod           # Go 模块定义
├── go.sum           # 依赖校验和
├── README.md        # 项目文档
└── mysql-mcp        # 编译后的可执行文件

依赖项

• github.com/modelcontextprotocol/go-sdk: MCP Go SDK
• github.com/go-sql-driver/mysql: MySQL 驱动

扩展功能建议

1. 连接池支持：为高并发场景添加数据库连接池
2. 事务支持：支持多语句事务操作
3. 批量操作：支持批量执行多个 SQL 语句
4. 结果集分页：对大结果集进行分页处理
5. 查询缓存：添加查询结果缓存机制
6. 监控和日志：添加详细的操作日志和性能监控

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

更新日志

v1.0.0

• 初始版本
• 支持基本的 MySQL 查询和 DML 操作
• 支持连接参数配置
• 提供结构化的 JSON 结果返回