MySQL MCP Server

为 AI 助手提供安全、受限的 MySQL 访问能力的 Model Context Protocol（MCP）服务器。它通过标准输入输出与 Cline、Cursor 等兼容 MCP 的客户端通信，自动在真实数据库和本地 Mock 数据之间切换，帮助你在开发阶段快速验证数据库交互逻辑。

功能亮点

• 多工具支持：
  • query_data：执行受限的 SQL 查询（支持 SELECT/SHOW/DESCRIBE/EXPLAIN）。
  • describe_table：读取并返回表结构。
  • create_table：在允许的范围内创建新表。
• 自动化资源暴露：通过 MCP 资源接口列出数据库中的表，并返回结构与示例数据，方便 AI 助手理解数据库模式。
• Mock 回退模式：当无法连接指定的数据库时自动启用内置的 Mock 数据，确保在没有真实数据库时仍能调试工具调用流程。
• 严格的安全限制：SQL 语句会在执行前经过验证，禁止执行写操作或潜在的破坏性语句。

架构概览

┌──────────────┐       ┌─────────────────────────┐       ┌──────────────┐
│ MCP 客户端  │ ←→ stdio ←→ │ mysql-mcp (Node.js + MCP SDK) │ ←→ │ MySQL 数据库 │
└──────────────┘       └─────────────────────────┘       └──────────────┘
                                             ↑
                                             └─ 无法连接时退回 Mock 数据

核心逻辑位于 src/index.ts：

1. 启动时初始化 MySQL 连接池，失败则进入 Mock 模式。
2. 向 MCP 客户端暴露工具清单与数据库资源列表。
3. 接收 AI 助手的工具调用请求，验证 SQL 后执行并返回 JSON 结果。

环境要求

• Node.js ≥ 18
• npm ≥ 9
• 可选：可访问的 MySQL 8.x 数据库（如无，可利用 Mock 模式）

快速开始

# 克隆仓库
git clone https://github.com/<your-org>/mysql-mcp.git
cd mysql-mcp

# 安装依赖并构建（会输出 build/index.js）
npm install
npm run build

构建完成后，可直接通过 Node 运行生成的二进制：

MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASSWORD=secret MYSQL_DATABASE=mydb \
  node build/index.js

配置 MCP 客户端

项目提供了多份示例配置文件，可根据需要选择：

文件	用途
mcp-config.json	通用 MCP 配置，适合 Cursor / Cline
cursor-mcp-config.json	Cursor 专用配置样例
augment-*.json	针对 Augment 等客户端的预置配置

将 command 指向 node，args 指向 ./build/index.js，并通过 env 设置连接数据库所需的环境变量。

Cursor 桌面端示例

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "cursor",
        "MYSQL_PASSWORD": "<password>",
        "MYSQL_DATABASE": "sample"
      }
    }
  }
}

将上述内容保存到：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Cline (Cursor 插件) 示例

# macOS
cp mcp-config.json "~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"

# Windows
cp mcp-config.json "%APPDATA%/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"

💡 在初次接入时，可先保留默认的 Mock 数据库配置，确保工具调用流程正常，再替换为真实数据库连接。

环境变量

变量	默认值	说明
MYSQL_HOST	127.0.0.1	MySQL 主机地址
MYSQL_PORT	3309	端口号
MYSQL_USER	erp_dev	数据库用户名
MYSQL_PASSWORD	空字符串	数据库密码（建议通过安全方式提供）
MYSQL_DATABASE	erp_dev	目标数据库

⚠️ 默认端口为 3309，若连接的是本地 MySQL，通常需要改为 3306。

Mock 模式

当数据库连接初始化失败时，服务器会记录错误并开启 Mock 模式：

• SHOW TABLES 返回 users、products、orders。
• DESCRIBE/SELECT/EXPLAIN 会返回与上述表相关的内置示例数据。
• CREATE TABLE 返回成功响应但不做实际操作。

Mock 模式非常适合在没有数据库凭据或网络受限的环境下演示工具能力。

安全策略

• 在 executeQuery 之前会调用 validateSQL，仅允许 SELECT、SHOW、DESCRIBE/DESC、EXPLAIN 以及 CREATE TABLE 语句。
• 所有输入的 SQL 会移除注释并进行首词校验，从而阻止 DROP、INSERT 等危险操作。
• 返回结果会限制在最多 1000 行，避免超大结果集导致内存压力。

开发与调试

• 源码位于 src/index.ts，使用 TypeScript 编写。
• 使用 npm run watch 进行增量编译，或 npm run build 生成可执行产物。
• 运行 npx @modelcontextprotocol/inspector build/index.js 可以在浏览器中调试 MCP 交互过程。

推荐的开发流程：

# 1. 启动 TypeScript watch
npm run watch

# 2. 在另一个终端中运行 inspector
npx @modelcontextprotocol/inspector build/index.js

常见问题

1. 无法连接数据库：
   • 确认 MySQL 服务已启动并能从本地访问。
   • 检查环境变量是否正确，尤其是端口号和数据库名称。
   • 观察终端日志，若看到 Falling back to mock mode，说明已进入 Mock。
2. 工具返回 Invalid SQL：
   • SQL 语句包含不受允许的操作，可先在本地验证语法并确保仅包含只读操作。
3. 结果集过大被截断：
   • 系统默认返回前 1000 行，可在 SQL 中主动添加 LIMIT。

进一步集成

• 可结合 test-mysql-mcp.js 等集成测试脚本验证 MCP 服务器的行为。
• 若需扩展更多工具（如写操作），请在 validateSQL 中加上严格的白名单逻辑，并在 CallToolRequestSchema 处理器中实现具体操作。

---

如需更多帮助，可参考项目中的配置示例文件或自定义扩展脚本。欢迎根据自身需求调整安全策略与工具集合。