MySQL 查询 MCP 服务器

一个模型上下文协议 (MCP) 服务器，为 AI 助手提供只读 MySQL 数据库查询。 直接从您的 AI 驱动工具执行查询、探索数据库结构和调查您的数据。

支持的 AI 工具

此 MCP 服务器适用于任何支持模型上下文协议的工具，包括：

• Cursor IDE: 在 .cursor/mcp.json 中设置
• Anthropic Claude: 与兼容的 MCP 客户端一起使用
• 其他 MCP 兼容的 AI 助手: 按照工具的 MCP 配置说明进行操作

功能和限制

它能做什么

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

它不能做什么

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

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

快速安装

# 使用 npm 全局安装
npm install -g mysql-query-mcp-server

# 或使用 npx 直接运行
npx mysql-query-mcp-server

设置说明

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

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

基本配置：

{
  "mysql": {
    "name": "MySQL 查询 MCP",
    "description": "通过 MCP 进行 MySQL 只读查询访问",
    "type": "bin", 
    "enabled": true,
    "bin": "mysql-query-mcp"
  }
}

包含数据库凭据的全面配置：

{
  "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 查询 MCP 服务器提供三个主要的工具，您的 AI 助手可以使用：

1. query

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

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

2. info

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

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

3. environments

从您的配置中列出所有已配置的环境：

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

可用工具

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

1. query

执行只读 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。

贡献

欢迎贡献！ 请随时提交拉取请求。

CI/CD 和发布流程

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

CI/CD 工作流程

CI/CD 管道包括：

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

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

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

   • 使用 release-please 管理版本更新和变更日志更新
   • 基于约定式提交创建包含版本更改的发布 PR
   • 在合并发布 PR 时自动发布到 npm

发布流程

该项目遵循 语义版本控制:

• 主要版本: 破坏性更改（非向后兼容）
• 次要版本: 新功能（向后兼容）
• 补丁版本: 错误修复和小的改进

提交应遵循 约定式提交 格式：

• 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。