MySQL 查询 MCP 服务器

这是一个 Model Context Protocol (MCP) 服务器，为 AI 助手提供只读的 MySQL 数据库查询。执行查询、探索数据库结构，并直接从您的 AI 工具中调查数据。

支持的 AI 工具

此 MCP 服务器与任何支持 Model Context Protocol 的工具兼容，包括：

• Cursor IDE: 在 .cursor/mcp.json 中设置
• Anthropic Claude: 使用兼容的 MCP 客户端
• 其他 MCP 兼容的 AI 助手: 请遵循工具的 MCP 配置说明

功能与限制

功能

• ✅ 执行只读 MySQL 查询（仅限 SELECT, SHOW, DESCRIBE）
• ✅ 与预定义环境（本地、开发、测试、生产）配合使用
• ✅ 提供数据库信息和元数据
• ✅ 列出可用的数据库环境
• ✅ 支持 SSL 连接以确保安全访问数据库
• ✅ 实现查询超时以防止长时间运行的操作

不支持的功能

• ❌ 执行写操作（INSERT, UPDATE, DELETE, CREATE, ALTER 等）
• ❌ 支持自定义环境名称（仅限于本地、开发、测试、生产）
• ❌ 提供数据库设计或模式生成功能
• ❌ 作为完整的数据库管理工具

该工具专门用于通过只读查询进行数据调查和探索。它不适用于数据库管理、模式管理和数据修改。

快速安装

bash

使用 npm 全局安装

npm install -g mysql-query-mcp-server

或者直接使用 npx 运行

npx mysql-query-mcp-server

设置说明

配置您的 AI 工具以使用 MCP 服务器

创建或编辑您的 MCP 配置文件（例如，对于 Cursor IDE 是 .cursor/mcp.json）：

基本配置：
json
{
"mysql": {
"name": "MySQL 查询 MCP",
"description": "通过 MCP 访问 MySQL 只读查询",
"type": "bin",
"enabled": true,
"bin": "mysql-query-mcp"
}
}

包含数据库凭据的全面配置：
json
{
"mysql": {
"command": "npx",
"args": ["mysql-query-mcp-server@latest"],
"env": {
"LOCAL_DB_HOST": "localhost",
"LOCAL_DB_USER": "root",
"LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
"LOCAL_DB_NAME": "your_database",
"LOCAL_DB_PORT": "3306",

  "DEVELOPMENT_DB_HOST": "dev.example.com",
  "DEVELOPMENT_DB_USER": "<DEV_USER>",
  "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
  "DEVELOPMENT_DB_NAME": "your_database",
  "DEVELOPMENT_DB_PORT": "3306",
  
  "STAGING_DB_HOST": "staging.example.com",
  "STAGING_DB_USER": "<STAGING_USER>",
  "STAGING_DB_PASS": "<STAGING_PASSWORD>",
  "STAGING_DB_NAME": "your_database",
  "STAGING_DB_PORT": "3306",
  
  "PRODUCTION_DB_HOST": "prod.example.com",
  "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
  "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
  "PRODUCTION_DB_NAME": "your_database",
  "PRODUCTION_DB_PORT": "3306",
  
  "DEBUG": "false",
  "MCP_MYSQL_SSL": "true",
  "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
}

}
}

选择正确的配置方法

有两种方式来配置 MySQL MCP 服务器：

1. 二进制配置 (type: "bin", bin: "mysql-query-mcp")

   • 何时使用: 当您已全局安装了该包 (npm install -g mysql-query-mcp-server)
   • 优点: 配置更简单
   • 缺点: 需要全局安装

2. 命令配置 (command: "npx", args: ["mysql-query-mcp-server@latest"])- 使用时机：当你希望使用最新版本但不想全局安装时

   • 优点：无需全局安装，所有配置在一个文件中
   • 缺点：配置较为复杂

选择最适合你工作流程的方法。这两种方法都可以与支持MCP的任何AI助手正确配合。

重要配置说明

• 你必须使用完整的环境名称：LOCAL_、DEVELOPMENT_、STAGING_、PRODUCTION_
• 缩写如DEV_或PROD_将不起作用
• 全局设置如DEBUG、MCP_MYSQL_SSL适用于所有环境
• 至少需要配置一个环境（通常是“local”）
• 你只需要配置计划使用的环境
• 出于安全考虑，请考虑为生产环境凭据使用环境变量或安全凭证存储

配置选项

环境变量	描述	默认值
DEBUG	启用调试日志	false
[ENV]_DB_HOST	指定环境的数据库主机	-
[ENV]_DB_USER	数据库用户名	-
[ENV]_DB_PASS	数据库密码	-
[ENV]_DB_NAME	数据库名	-
[ENV]_DB_PORT	数据库端口	3306
[ENV]_DB_SSL	启用SSL连接	false
MCP_MYSQL_SSL	为所有连接启用SSL	false
MCP_MYSQL_REJECT_UNAUTHORIZED	验证SSL证书	true

与AI助手集成

你的AI助手可以通过MCP服务器与MySQL数据库交互。以下是一些示例：

示例查询：

你能使用查询工具从本地环境中显示数据库中的前10个用户吗？

我需要分析我们的销售数据。你能运行一个SQL查询来获取上个月开发数据库中按地区划分的总销售额吗？

你能使用info工具检查暂存数据库中有哪些表可用吗？

你能列出我们已配置的所有可用数据库环境吗？

使用MySQL MCP工具

MySQL Query MCP服务器提供了三个主要工具供你的AI助手使用：

1. query

对特定环境执行只读SQL查询：

使用query工具运行：
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
在开发环境中

2. info

获取关于你的数据库的详细信息：

使用info工具检查我们的生产数据库的状态。

3. environments

列出配置中的所有环境：

使用environments工具向我展示哪些数据库环境是可用的。

可用工具

MySQL Query MCP服务器提供三个主要工具：

1. query

执行只读SQL查询：

sql
-- 使用query工具运行的示例查询
SELECT * FROM users LIMIT 10;

支持的查询类型（严格限制为）：

• SELECT语句
• SHOW命令
• DESCRIBE/DESC表

2. info

获取关于你的数据库的详细信息：

• 服务器版本
• 连接状态
• 数据库变量
• 进程列表
• 可用数据库

3. environments

列出配置中的所有环境：

使用environments工具向我展示哪些数据库环境是可用的。

安全注意事项

• ✅ 仅允许只读查询（SELECT, SHOW, DESCRIBE）
• ✅ 每个环境都有自己的隔离连接池
• ✅ 支持生产环境的SSL连接
• ✅ 查询超时防止失控操作
• ⚠️ 考虑为数据库凭据使用安全凭证管理

故障排除

连接问题

如果你遇到连接问题：

1. 在MCP配置中验证你的数据库凭据
2. 确保MySQL服务器正在运行且可访问
3. 检查是否有防火墙规则阻止了连接
4. 通过在配置中设置DEBUG=true启用调试模式

常见错误

错误：没有可用于该环境的连接池- 确保已为该环境定义了所有必需的环境变量

• 检查是否使用了支持的环境名称（local, development, staging, production）

错误：查询执行失败

• 验证您的 SQL 语法
• 检查您是否仅使用了支持的查询类型（SELECT, SHOW, DESCRIBE）
• 确保您的查询确实是只读的

有关更全面的故障排除，请参阅 故障排除指南。

有关如何与 AI 助手集成的示例，请参阅 集成示例。

有关 MCP 协议实现细节，请参阅 MCP README。

贡献

欢迎贡献！请随时提交 Pull Request。

CI/CD 和发布流程

此项目使用 GitHub Actions 进行持续集成和自动化发布。

CI/CD 工作流

CI/CD 流水线包括：

1. 构建和测试：在每次推送到 main 和 develop 分支时，以及向这些分支发起拉取请求时运行

   • 使用 Node.js 16.x 和 18.x 测试代码库
   • 确保包正确构建
   • 验证所有测试通过

2. 发布：当更改被推送到 main 分支且构建/测试作业成功时运行

   • 使用 release-please 管理版本更新和变更日志更新
   • 根据常规提交创建包含版本更改的发布 PR
   • 当发布 PR 合并时自动发布到 npm

发布流程

该项目遵循 语义化版本控制：

• 主版本：破坏性变更（不向后兼容）
• 次版本：新功能（向后兼容）
• 补丁版本：修复 Bug 和小改进

提交应遵循 常规提交 格式：

• feat: add new feature - 次版本更新
• fix: resolve bug - 补丁版本更新
• docs: update documentation - 不更新版本
• chore: update dependencies - 不更新版本
• BREAKING CHANGE: change API - 主版本更新

当您推送到 main 时，release-please 将分析提交并自动创建或更新带有适当版本更新和变更日志条目的发布 PR。

许可证

此项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。

作者

Abou Koné - 工程负责人兼 CTO

---

如需更多信息或支持，请在 GitHub 仓库中 打开一个 issue。