Skip to main content
Glama
guangxiangdebizi

MySQL MCP Server

by guangxiangdebizi
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

MySQL MCP Server 🚀

v4.0.0 - 全新架构重写，更简洁、更强大！

一个功能强大且易用的 MySQL 数据库 MCP（Model Context Protocol）服务器，支持 AI 助手安全地操作 MySQL 数据库。

🌟 核心特性

  • 🌐 StreamableHTTP 协议 - 基于最新 MCP 规范实现

  • 🔐 Header 预配置 - 凭证不暴露给 AI，安全可靠

  • 🤖 AI 动态管理 - AI 可以帮你添加/切换数据库连接

  • 🔗 多数据库支持 - 同时管理多个数据库，随时切换

  • 📊 完整 CRUD - 支持所有 SQL 操作

  • 🏗️ 模块化架构 - 清晰的目录结构，易于扩展

📦 安装

环境要求

  • Node.js 18+

  • MySQL 5.7+ 或 8.0+

  • MCP 客户端（Claude Desktop、Cursor 等）

安装步骤

# 克隆项目 git clone https://github.com/guangxiangdebizi/MySQL_MCP.git cd MySQL_MCP # 安装依赖 npm install # 编译 npm run build # 启动服务器 npm start

⚙️ 配置方法

方式一：Header 预配置（推荐）

编辑 MCP 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

单数据库配置

{ "mcpServers": { "mysql-mcp": { "type": "streamableHttp", "url": "http://localhost:3001/mcp", "timeout": 600, "headers": { "X-MySQL-Host": "localhost", "X-MySQL-Port": "3306", "X-MySQL-User": "root", "X-MySQL-Password": "your_password", "X-MySQL-Database": "your_database" } } } }

多数据库配置

{ "mcpServers": { "mysql-mcp": { "type": "streamableHttp", "url": "http://localhost:3001/mcp", "timeout": 600, "headers": { "X-MySQL-Host-1": "prod.mysql.com", "X-MySQL-User-1": "prod_user", "X-MySQL-Password-1": "prod_pass", "X-MySQL-Database-1": "production", "X-MySQL-Host-2": "test.mysql.com", "X-MySQL-User-2": "test_user", "X-MySQL-Password-2": "test_pass", "X-MySQL-Database-2": "testing" } } } }

优势：

  • ✅ 数据库凭证不暴露给 AI

  • ✅ 启动即连接，无需手动操作

  • ✅ 支持多数据库同时连接

方式二：AI 动态添加（灵活）

不配置 Header，让 AI 在对话中帮你添加连接：

{ "mcpServers": { "mysql-mcp": { "type": "streamableHttp", "url": "http://localhost:3001/mcp", "timeout": 600 } } }

使用示例：

你: 帮我连接到本地 MySQL，用户名 root，密码 123456，数据库 mydb AI: [调用 add_connection 工具]

🔧 工具列表

连接管理

工具名称

功能说明

使用场景

add_connection

添加数据库连接

AI 帮你动态添加新连接

list_connections

列出所有连接

查看当前有哪些数据库

select_database

选择活跃数据库

切换到其他数据库

remove_connection

移除连接

清理不需要的连接

查询操作

工具名称

功能说明

使用场景

execute_query

执行 SQL

任何 SQL 操作（SELECT、INSERT、UPDATE、DELETE）

show_tables

显示所有表

快速了解数据库结构

describe_table

查看表结构

查看字段、类型、样本数据

show_databases

显示所有数据库

查看可访问的数据库列表

🎮 使用示例

场景一：使用 Header 预配置

你: 显示所有表 AI: [调用 show_tables] 📊 数据库表列表 (共 5 个表) 1. users 2. orders 3. products ... 你: 查看 users 表的结构 AI: [调用 describe_table，参数：users] 📋 表结构: users 字段信息: - id (INT, 主键) - name (VARCHAR) - email (VARCHAR) ...

场景二：AI 动态添加连接

你: 帮我连接两个数据库： 1. 生产库：prod.mysql.com，用户 admin，密码 xxx，数据库 shop 2. 测试库：test.mysql.com，用户 tester，密码 yyy，数据库 shop_test AI: [调用 add_connection，参数：id=prod, host=prod.mysql.com...] [调用 add_connection，参数：id=test, host=test.mysql.com...] ✅ 两个数据库连接已添加 你: 列出所有连接 AI: [调用 list_connections] 📊 当前数据库连接列表 (共 2 个) 🟢 [1] prod └─ prod.mysql.com:3306/shop └─ ✅ 当前活跃连接 ⚪ [2] test └─ test.mysql.com:3306/shop_test 你: 切换到测试库 AI: [调用 select_database，参数：test] ✅ 已选择数据库: test 你: 查询用户表前 10 条 AI: [调用 execute_query，SQL: SELECT * FROM users LIMIT 10] ✅ 查询成功，返回 10 行数据 [显示 JSON 格式数据]

🏗️ 项目架构

MySQL_MCP/ ├── src/ │ ├── index.ts # 主入口（HTTP Server + 会话管理） │ ├── database.ts # 数据库连接管理器 │ └── tools/ # 工具模块 │ ├── index.ts # 工具统一导出和路由 │ ├── connection.ts # 连接管理工具 │ └── query.ts # 查询工具 ├── dist/ # 编译后的 JS 文件 ├── package.json ├── tsconfig.json └── README.md

核心设计：

  • index.ts - Express HTTP 服务器 + MCP Server 初始化

  • database.ts - 封装数据库连接池和查询逻辑

  • tools/ - 每个文件负责一类工具的定义和处理

🔒 安全建议

数据库权限配置

为 MCP 创建专用数据库用户，限制权限：

-- 创建专用用户 CREATE USER 'mcp_user'@'%' IDENTIFIED BY 'strong_password'; -- 授予必要权限 GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'%'; -- 生产环境只读用户 GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';

HTTP 模式安全

  • ✅ 使用 Header 预配置，避免凭证暴露给 AI

  • ✅ 生产环境使用 HTTPS（Nginx 反向代理）

  • ✅ 限制访问 IP（防火墙规则）

  • ✅ 定期更新数据库密码

  • ✅ 监控日志，发现异常访问

🚀 NPM 脚本

# 开发模式（TypeScript 直接运行） npm run dev # 编译 npm run build # 生产模式（运行编译后的 JS） npm start # 全局安装 npm run install-global

📝 环境变量

创建 .env 文件（可选）：

# HTTP 服务器端口 PORT=3001 # Node 环境 NODE_ENV=production

❗ 常见问题

1. 端口被占用

错误： EADDRINUSE: address already in use :::3001

解决： 修改 .env 文件中的 PORT，或终止占用进程

# Windows netstat -ano | findstr :3001 taskkill /F /PID <PID> # Linux/Mac lsof -ti:3001 | xargs kill -9

2. 连接失败

错误： 数据库连接失败

检查：

  • MySQL 服务是否运行

  • 主机、端口、用户名、密码是否正确

  • 防火墙是否允许连接

3. 会话丢失

问题： 重启服务器后提示 "Session not found"

原因： 会话存储在内存中，重启后清空

解决： 刷新 MCP 客户端（重新初始化）

4. 连接已关闭错误

错误： Can't add new command when connection is in closed state

原因：

  • 数据库连接长时间空闲，MySQL 服务器关闭了连接

  • 网络中断导致连接断开

解决方案：

  • ✅ v4.0.5+ 已使用连接池替代单连接，自动支持：

    • 连接保活（Keep-Alive）机制

    • 自动重连功能

    • 并发查询支持

  • 如果仍遇到问题，请重启 MCP 服务器

📦 版本历史

v4.0.5 (2025-12-09) - 连接池优化

  • 🎯 使用连接池替代单连接

  • 🔄 自动连接保活（Keep-Alive）

  • 🔌 自动重连机制

  • 🚀 支持并发查询

  • 🐛 修复 "connection in closed state" 错误

v4.0.0 (2025-12-09) - 全新架构

  • 🔥 完全重写，全新模块化架构

  • ✨ 基于最新 MCP StreamableHTTP 协议

  • 🎯 简化工具：连接管理 + 查询操作

  • 🏗️ 清晰的目录结构：tools/ 模块化

  • 🚀 更快的响应速度

  • 📖 更清晰的代码注释

v3.x - 旧版本

  • 支持事务管理、回滚等复杂功能

  • 较为复杂的架构

📞 支持与反馈

🔧 故障排除

问题：ERR_MODULE_NOT_FOUND 错误

错误信息：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...@modelcontextprotocol/sdk...'

解决方案：

  1. 删除并重新安装依赖：

# 删除旧依赖 rm -rf node_modules package-lock.json # Linux/Mac # 或 rmdir /s /q node_modules && del package-lock.json # Windows # 清理缓存 npm cache clean --force # 重新安装 npm install

  1. 检查 Node.js 版本：

node --version # 需要 >= 18.0.0

  1. 使用全局安装：

npm install -g @xingyuchen/mysql-mcp-server@latest

问题：SSE 流断开

错误信息：

SSE stream disconnected: TypeError: terminated

解决方案：

在 mcp.json 中设置更长的超时或禁用超时：

{ "mysql-mcp-http": { "type": "streamableHttp", "url": "http://localhost:3002/mcp", "timeout": 0, // 0 表示无超时限制 "headers": { ... } } }

问题：安全漏洞警告

警告信息：

npm audit: vulnerabilities found

解决方案：

# 自动修复 npm audit fix # 如果还有问题，强制修复 npm audit fix --force # 重新构建 npm run build

问题：端口被占用

错误信息：

Error: listen EADDRINUSE: address already in use :::3002

解决方案：

  1. 更改端口（在 .env 文件中）：

PORT=3003

  1. 或者关闭占用端口的进程：

# Windows netstat -ano | findstr :3002 taskkill /PID <进程ID> /F # Linux/Mac lsof -i :3002 kill -9 <进程ID>

获取更多帮助

📄 License

Apache 2.0 License - 详见 LICENSE 文件

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/guangxiangdebizi/MySQL_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server