MySQL MCP Server

基于 Model Context Protocol (MCP) 的 MySQL 数据库访问服务，供大模型通过标准化的工具接口对 MySQL 执行查询、增删改、表结构查看等操作。

特性

• 4 个 MCP 工具：mysql_query / mysql_execute / mysql_list / mysql_describe
• Streamable HTTP 传输：基于 HTTP 的流式传输，适合远程调用场景
• 参数化查询：使用 ? 占位符绑定参数，防止 SQL 注入
• 连接池：mysql2 连接池复用连接，支持并发
• 只读模式开关：开启后仅允许读操作，防止误删数据
• 凭据环境变量化：所有敏感信息通过 .env 注入，不硬编码

技术栈

• TypeScript + Node.js 18+
• @modelcontextprotocol/sdk（官方 MCP SDK）
• mysql2（纯 JS MySQL 驱动，支持 Promise）
• zod（参数校验）

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制示例配置文件并填写你的 MySQL 连接信息：

cp .env.example .env

编辑 .env：

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

MYSQL_POOL_SIZE=10
MYSQL_READ_ONLY=false

MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000

3. 编译

npm run build

4. 启动服务

npm start

服务启动后监听 http://127.0.0.1:3000/mcp，MCP 端点为 /mcp（支持 POST / GET / DELETE）。

开发模式（监听文件变化自动编译）：

npm run dev

工具说明

工具	用途	入参	只读模式
mysql_query	执行返回结果集的语句（SELECT）	sql, params?, database?	仅允许 SELECT/SHOW/DESCRIBE/EXPLAIN
mysql_execute	执行 DDL（CREATE/ALTER/DROP）和 DML（INSERT/UPDATE/DELETE）	sql, params?, database?	完全禁用
mysql_list	列出所有数据库或指定库的表	type: "databases"|"tables", database?	允许
mysql_describe	查看表的列定义	table, database?	允许

使用示例

查询数据：

{
  "sql": "SELECT id, name, email FROM users WHERE age > ? ORDER BY id LIMIT ?",
  "params": [18, 10]
}

插入数据：

{
  "sql": "INSERT INTO users (name, email) VALUES (?, ?)",
  "params": ["Alice", "alice@example.com"]
}

列出数据库：

{ "type": "databases" }

查看表结构：

{ "table": "users" }

安全设计

• 凭据管理：所有 MySQL 连接信息通过环境变量注入，.env 已加入 .gitignore
• SQL 注入防护：所有用户输入通过 mysql2 的 ? 占位符参数绑定，表名等标识符通过白名单校验
• 只读模式：MYSQL_READ_ONLY=true 时，mysql_query 仅允许 SELECT 类语句，mysql_execute 完全禁用
• 连接池限制：通过 MYSQL_POOL_SIZE 限制最大连接数，防止资源泄露
• 错误信息：MySQL 错误返回结构化信息（errno、sqlMessage），不暴露凭据

MCP Client 对接

在 Claude Desktop / Cursor 等客户端中配置

由于本服务使用 Streamable HTTP 传输，在 MCP Client 配置中添加：

{
  "mcpServers": {
    "mysql": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

项目结构

├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── README.md
└── src/
    ├── index.ts              # 入口：HTTP 服务 + MCP Server
    ├── config.ts             # 环境变量读取与校验
    ├── db.ts                 # mysql2 连接池封装
    ├── guard.ts              # 只读模式守卫
    └── tools/
        ├── index.ts          # 工具注册总入口
        ├── query.ts          # mysql_query
        ├── execute.ts        # mysql_execute
        ├── list.ts           # mysql_list
        └── describe.ts       # mysql_describe

License

MIT