MySQL Query MCP Server

MySQL Query 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）
• ✅ 使用预定义环境（local、development、staging、production）
• ✅ 提供数据库信息和元数据
• ✅ 列出可用的数据库环境
• ✅ 支持 SSL 连接，安全访问数据库
• ✅ 实施查询超时，防止操作长时间运行

不支持的功能

• ❌ 执行写入操作（INSERT、UPDATE、DELETE、CREATE、ALTER 等）
• ❌ 支持自定义环境名称（仅限 local、development、staging、production）
• ❌ 提供数据库设计或模式生成能力
• ❌ 作为完整的数据库管理工具运行

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

快速安装

# Install globally with npm
npm install -g mysql-query-mcp-server

# Or run directly with npx
npx mysql-query-mcp-server

设置说明

配置 AI 工具以使用 MCP 服务

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

基本配置：

{
  "mysql": {
    "name": "MySQL Query MCP",
    "description": "MySQL read-only query access through MCP",
    "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_TIMEZONE": "Z"
    }
  }
}

选择合适的配置方式

配置 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"）
• 只需配置计划使用的环境
• 出于安全考虑，生产环境凭据建议使用环境变量或安全凭据存储
• DATETIME、DATE 和 TIMESTAMP 列将以字符串形式返回，以保留 MySQL 中存储的精确值，避免受主机时区转换影响

配置选项

环境变量	描述	默认值
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
MYSQL_TIMEZONE	mysql2 在查询中发送 JavaScript Date 值时使用的时区	Z

日期和时间值

MySQL 的 DATETIME、DATE 和 TIMESTAMP 列会以原始字符串形式返回，例如 2026-05-13 16:12:08。这样可以保留存储的确切值，并防止 Node 主机时区在 JSON 序列化期间改变结果。

MYSQL_TIMEZONE 默认为 Z（UTC）。仅当应用有意使用不同的连接时区向 MySQL 发送 JavaScript Date 对象时，才覆盖此设置。

如果调用方已经将日期/时间值作为字符串处理，则无需更改。此前预期从此 MCP 服务获得 JavaScript Date 对象的调用方，应显式解析返回的字符串。

与 AI 助手集成

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

示例查询：

Can you use the query tool to show me the first 10 users from the database? Use the local environment.

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you use the info tool to check what tables are available in the staging database?

Can you list all the available database environments we have configured?

使用 MySQL MCP 工具

MySQL Query MCP 服务提供三个主要工具，AI 助手可以使用这些工具：

1. query

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

Use the query tool to run:
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
on the development environment

2. info

获取数据库的详细信息：

Use the info tool to check the status of our production database.

3. environments

列出配置中的所有环境：

Use the environments tool to show me which database environments are available.

可用工具

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

1. query

执行只读 SQL 查询：

-- Example query to run with the query tool
SELECT * FROM users LIMIT 10;

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

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

2. info

获取数据库的详细信息：

• 服务器版本
• 连接状态和运行时间
• 所选服务器变量（字符集、时区、超时设置、连接限制）
• 连接计数器（已连接线程、运行中的线程、查询数量）
• 可用数据库

不会报告完整的 SHOW VARIABLES 输出和服务器进程列表。 请参阅 SECURITY.md。

3. environments

列出配置中的所有环境：

Use the environments tool to show me which database environments are available.

安全注意事项

• ✅ 仅允许只读查询（SELECT、SHOW、DESCRIBE）
• ✅ 每个环境都有独立的连接池
• ✅ 支持生产环境使用 SSL 连接
• ✅ 查询超时可防止操作失控
• ✅ 工具响应不会包含配置值，并会在返回前检查是否含有机密信息
• ⚠️ 凭据仍以明文环境变量的形式配置在 MCP 客户端配置中。请勿将该文件纳入版本控制

如果你使用的是 1.3.0 之前的版本

截至 1.2.2 的版本会在 environments 工具响应中返回数据库凭据，这意味着这些凭据可能已写入 AI 聊天记录。 **请轮换通过此服务配置的所有凭据。**详情请参阅 SECURITY.md。

故障排除

连接问题

如果连接遇到问题：

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 分支，以及向这些分支提交 Pull Request 时运行

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