🚀 MySQL MCP Server
通过模型上下文协议(MCP),让Claude AI直接访问你的MySQL数据库。
MySQL MCP Server允许Claude Desktop和Claude Code执行SQL查询、探索数据库,并与你的MySQL数据进行交互——所有这些都通过一个安全的、可控制权限的接口实现。
🚀 快速开始
安装
npm install -g mysql-mcp-webui
npx mysql-mcp-webui
Claude Desktop设置指南
重要提示:在配置Claude Desktop之前,你必须先生成一个API令牌。请按以下步骤操作:
步骤1:生成API令牌
在设置Claude Desktop之前,先生成一个认证令牌:
mysql-mcp-webui --generate-token
这将输出类似如下内容:
✓ API令牌生成成功!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
mcp_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 重要提示:请安全保存此令牌!
此令牌不会再次显示。
复制此令牌,你将在下一步中用到它。
步骤2:配置Claude Desktop
将以下配置添加到你的Claude Desktop配置文件中:
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
配置内容:
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "mysql-mcp-webui"],
"env": {
"TRANSPORT": "stdio",
"AUTH_TOKEN": "paste-your-token-here"
}
}
}
}
替换 paste-your-token-here 为步骤1中生成的令牌。
注意:如果你使用 npm install -g 进行了全局安装,也可以使用 "command": "mysql-mcp-webui" 而无需 args 字段。
步骤3:启动Claude Desktop
- 保存 配置文件。
- 完全 重启Claude Desktop(退出并重新打开)。
- Claude Desktop将自动启动MCP服务器。
- Web UI 可在 http://localhost:9274 访问。
步骤4:配置MySQL连接
打开 http://localhost:9274 的Web UI:
- 使用默认凭据
admin / admin 登录。
- 添加MySQL连接:
- 输入你的MySQL服务器主机名、端口、用户名和密码。
- 点击“测试连接”以验证连接是否正常。
- 发现数据库:
- 设置权限:
- 对于每个数据库,启用Claude可以执行的操作。
- 对于生产数据库,建议从 仅允许SELECT 开始。
- 设置默认连接(可选):
- 这将使启动新的Claude Desktop实例更加方便。
步骤5:开始使用Claude
你已完成所有设置!现在你可以要求Claude查询你的数据库:
你:“按注册日期显示前10名用户”
Claude:[使用mysql_query工具获取数据]
设置故障排除
“AUTH_TOKEN is required”错误:
- 确保你首先运行了
mysql-mcp-webui --generate-token 命令。
- 验证令牌是否正确粘贴到配置文件中(无多余空格或引号)。
- 检查配置文件是否为有效的JSON格式。
Claude Desktop无法识别MCP服务器:
- 验证配置文件的位置是否适用于你的操作系统。
- 完全重启Claude Desktop(退出并重新打开,而不仅仅是重新加载)。
- 检查JSON文件中是否存在语法错误(可使用JSON验证器)。
Web UI无法访问:
- 服务器仅在Claude Desktop启动时才会启动。
- 检查端口9274是否已被占用:
lsof -i :9274(macOS/Linux)。
- 尝试通过在
env 部分添加 "HTTP_PORT": "3001" 来使用不同的端口。
✨ 主要特性
什么是MCP?
模型上下文协议 是一个开放标准,它允许像Claude这样的AI助手安全地连接到外部数据源和工具。这个MySQL MCP Server实现了该协议,使Claude能够:
- 🔍 查询你的数据库 - 使用自然语言执行SQL查询
- 📊 探索你的数据 - 浏览表、了解模式并分析数据
- 🔄 切换上下文 - 无缝切换不同的数据库
- 🔒 保持安全 - 每个操作都根据你的权限规则进行验证
四大MCP工具
配置完成后,Claude可以使用四个强大的工具与你的MySQL数据库进行交互:
1. mysql_query - 执行SQL查询
Claude可以针对你当前的数据库运行SQL查询,并自动验证权限。
示例对话:
你:“按注册日期显示前10名用户”
Claude使用:mysql_query
SQL:SELECT id, username, email, created_at
FROM users
ORDER BY created_at DESC
LIMIT 10
响应:[查询结果以表格形式显示]
执行过程:
- Claude根据你的请求生成适当的SQL。
- 根据数据库权限验证查询(例如,必须具有SELECT权限)。
- 在事务中执行查询(出错时自动回滚)。
- 格式化结果以便于阅读。
2. list_databases - 探索可用数据库
Claude可以查看你配置的所有数据库及其权限。
示例对话:
你:“我可以访问哪些数据库?”
Claude使用:list_databases
参数:{ include_metadata: true }
响应:
- production_db (活动)
权限:SELECT
表数量:45
大小:2.3 GB
- staging_db
权限:SELECT, INSERT, UPDATE
表数量:42
大小:856 MB
执行过程:
- 列出你当前MySQL连接中的所有数据库。
- 显示当前活动的数据库。
- 显示每个数据库的配置权限。
- 可选地包含元数据(表数量、大小)。
3. switch_database - 更改活动数据库
Claude可以使用数据库别名在你的MySQL连接中切换数据库。
示例对话:
你:“让我们查看暂存数据库”
Claude使用:switch_database
参数:{ database: "staging_db" }
响应:✓ 已从production_db切换到staging_db
权限:SELECT, INSERT, UPDATE, DELETE
你现在可以在staging_db中查询数据并进行修改
执行过程:
- 验证数据库是否存在于你的连接中。
- 切换所有未来查询的活动数据库。
- 返回新数据库的权限。
- 持久保存更改(重启后仍然有效)。
4. add_connection - 创建新的MySQL连接
Claude可以通过编程方式添加新的MySQL数据库连接,而无需使用Web UI。
示例对话:
你:“添加一个到本地MySQL服务器的连接,使用root用户,密码为'mypass'”
Claude使用:add_connection
参数:{
name: "Local MySQL",
host: "localhost",
port: 3306,
user: "root",
password: "mypass"
}
响应:✓ 连接创建成功!
连接ID:1
名称:Local MySQL
发现的数据库:发现5个数据库,并授予SELECT权限
执行过程:
- 通过测试连接验证连接凭据。
- 在存储之前使用AES - 256 - GCM加密密码。
- 将连接保存到数据库。
- 自动发现所有可用的数据库。
- 为发现的数据库授予默认的SELECT权限。
- 返回连接详细信息和发现结果。
工作原理
┌─────────────────────────────────────────────────────┐
│ 你:“显示本月注册的用户” │
└──────────────────┬──────────────────────────────────┘
│
┌──────────────────▼──────────────────────────────────┐
│ Claude Desktop / Claude Code │
│ - 理解你的请求 │
│ - 决定使用mysql_query工具 │
│ - 生成适当的SQL │
└──────────────────┬──────────────────────────────────┘
│ MCP协议
┌──────────────────▼──────────────────────────────────┐
│ MySQL MCP Server │
│ 1. 验证API令牌 │
│ 2. 检查数据库权限 │
│ 3. 解析SQL以验证允许的操作 │
│ 4. 在事务中执行查询 │
│ 5. 返回结果 │
└──────────────────┬──────────────────────────────────┘
│
┌──────────────────▼──────────────────────────────────┐
│ 你的MySQL数据库 │
│ - 安全执行查询 │
│ - 返回结果 │
└─────────────────────────────────────────────────────┘
权限系统
每个数据库都有细粒度的权限。你可以配置Claude可以执行的操作:
| 权限 |
允许的操作 |
示例用例 |
| SELECT |
从表中读取数据 |
"显示上周的所有订单" |
| INSERT |
添加新记录 |
"创建一个新的用户账户" |
| UPDATE |
修改现有记录 |
"更新用户的电子邮件地址" |
| DELETE |
删除记录 |
"删除垃圾评论" |
| CREATE |
创建表/索引 |
"创建一个新的分析表" |
| ALTER |
修改表结构 |
"向用户表中添加一个新列" |
| DROP |
删除表/数据库 |
"删除临时测试表" |
| TRUNCATE |
清空表 |
"清空日志表中的所有数据" |
最佳实践:对于生产数据库,建议从 仅允许SELECT 开始。根据需要授予其他权限。
用例
数据分析
你:“过去6个月的月收入趋势如何?”
Claude:使用mysql_query工具聚合销售数据并提供摘要
数据库探索
你:“哪些表包含客户信息?”
Claude:查询information_schema并解释表之间的关系
模式理解
你:“解释用户表的结构”
Claude:使用DESCRIBE查询并解释每列的用途
数据迁移
你:“将今年创建的所有用户复制到存档数据库”
Claude:切换数据库,查询源数据库,并插入到目标数据库
调试
你:“为什么会出现重复订单?”
Claude:查询订单表,分析数据并找出问题
Web UI功能
可在 http://localhost:9274 访问管理界面。
- 仪表盘 - 查看连接和活动的概述
- 连接 - 使用启用/禁用控件管理MySQL服务器连接
- 数据库 - 配置权限、启用/禁用数据库并管理自定义别名
- 浏览器 - 探索表、查看数据、检查索引
- 查询编辑器 - 使用语法高亮测试SQL查询
- API密钥 - 管理认证令牌
- 用户 - 多用户访问控制
- 日志 - 所有MCP工具调用的审计跟踪
- 暗模式 - 系统偏好检测
v0.1.0版本新增功能
- 数据库别名 - 为你的数据库创建自定义、用户友好的名称
- 连接控件 - 启用/禁用连接以控制哪些连接处于活动状态
- add_connection工具 - Claude现在可以通过编程方式添加MySQL连接
安全性
内置保护
✅ 权限验证 - 每个查询都根据数据库权限进行检查
✅ SQL解析 - 在执行前验证查询类型
✅ 事务安全 - 出错时自动回滚
✅ 密码加密 - 使用AES - 256 - GCM加密MySQL密码
✅ API密钥认证 - 基于令牌的访问控制
✅ 请求日志记录 - 完整的审计跟踪
✅ 速率限制 - 防止滥用
✅ 输入清理 - 防止SQL注入
最佳实践
- 对于生产数据库,最初使用 只读权限。
- 创建具有有限权限的专用MySQL用户。
- 通过Web UI 定期轮换API密钥。
- 查看审计日志 以监控Claude对数据库的访问。
- 仅启用所需的数据库 - 禁用其他数据库。
- 在生产环境中 使用HTTPS 进行远程访问。
多实例支持
安全地运行多个Claude Desktop实例或会话:
- stdio模式:每个Claude Desktop实例都有自己的进程
- HTTP模式:多个会话具有隔离的状态
- 并发访问:使用WAL模式安全地写入SQLite
- 会话清理:自动清理非活动会话(30分钟)
在Web UI中设置默认连接,以便所有新实例都以相同的设置启动。
📦 安装指南
安装
npm install -g mysql-mcp-webui
npx mysql-mcp-webui
Claude Code(HTTP模式)设置指南
Claude Code可以通过HTTP模式连接到MySQL MCP Server,允许远程访问和多个并发会话。
选项1:使用npx(无需Docker)
步骤1:启动服务器
TRANSPORT=http npx -y mysql-mcp-webui
TRANSPORT=http HTTP_PORT=3001 npx -y mysql-mcp-webui
步骤2:生成API令牌
打开 http://localhost:9274(或你的自定义端口)的Web UI:
- 使用默认凭据
admin / admin 登录。
- 导航到 API密钥 部分。
- 点击 生成新API密钥。
- 复制生成的密钥。
步骤3:配置Claude Code
将以下内容添加到你的Claude Code MCP设置中(.claude/mcp_settings.json 或通过UI):
{
"mcpServers": {
"mysql": {
"type": "http",
"url": "http://localhost:9274/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
对于远程/生产部署,使用你的域名:
{
"mcpServers": {
"mysql": {
"type": "http",
"url": "https://yourdomain.com/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
选项2:使用Docker(推荐用于生产环境)
步骤1:使用Docker部署
快速启动(无需克隆):
docker run -d \
--name mysql-mcp \
-p 9274:9274 \
-v mysql-mcp-data:/app/data \
-e TRANSPORT=http \
-e NODE_ENV=production \
mysql-mcp-webui
docker build -t mysql-mcp-webui https://github.com/yashagldit/mysql-mcp-webui.git
docker run -d \
--name mysql-mcp \
-p 9274:9274 \
-v mysql-mcp-data:/app/data \
-e TRANSPORT=http \
-e NODE_ENV=production \
mysql-mcp-webui
使用docker - compose(用于高级配置):
git clone https://github.com/yashagldit/mysql-mcp-webui.git
cd mysql-mcp-webui
cp .env.example .env
docker-compose up -d
步骤2:获取API密钥
步骤3:配置Claude Code
{
"mcpServers": {
"mysql": {
"type": "http",
"url": "http://localhost:9274/mcp",
"headers": {
"Authorization": "Bearer your-docker-api-key-here"
}
}
}
}
步骤4:配置MySQL连接
与Claude Desktop设置相同 - 使用Web UI进行以下操作:
- 添加MySQL连接
- 发现数据库
- 设置权限
- 可选地设置默认连接
Docker部署选项
基本HTTP模式
docker run -d \
--name mysql-mcp \
-p 9274:9274 \
-v mysql-mcp-data:/app/data \
mysql-mcp-webui
自定义端口
docker run -d \
--name mysql-mcp \
-p 3001:3001 \
-v mysql-mcp-data:/app/data \
-e HTTP_PORT=3001 \
mysql-mcp-webui
使用HTTPS(生产环境)
docker run -d \
--name mysql-mcp \
-p 443:9274 \
-v mysql-mcp-data:/app/data \
-v /etc/letsencrypt:/app/certs:ro \
-e ENABLE_HTTPS=true \
-e SSL_CERT_PATH=/app/certs/live/yourdomain.com/fullchain.pem \
-e SSL_KEY_PATH=/app/certs/live/yourdomain.com/privkey.pem \
mysql-mcp-webui
使用docker - compose.yml
仓库中包含一个现成的 docker-compose.yml:
services:
mysql-mcp:
image: mysql-mcp-webui
ports:
- "9274:9274"
volumes:
- mysql-mcp-data:/app/data
environment:
- TRANSPORT=http
- NODE_ENV=production
restart: unless-stopped
volumes:
mysql-mcp-data:
有关使用HTTPS进行详细生产部署、速率限制和安全加固的信息,请参阅 DEPLOYMENT.md。
💻 使用示例
基础用法
mysql-mcp-webui --help
mysql-mcp-webui --generate-token
mysql-mcp-webui --version
高级用法
自定义安装路径
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/path/to/mysql-mcp-webui/server/dist/index.js"],
"env": {
"TRANSPORT": "stdio",
"AUTH_TOKEN": "your-key"
}
}
}
}
生产部署
有关以下内容,请参阅 DEPLOYMENT.md:
- Docker部署
- HTTPS/TLS配置
- 速率限制设置
- 多实例架构
- 安全加固
开发
有关以下内容,请参阅 README_DEVELOPMENT.md:
📚 详细文档
配置选项
传输模式
stdio模式(Claude Desktop默认):
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "mysql-mcp-webui"],
"env": {
"TRANSPORT": "stdio",
"AUTH_TOKEN": "your-api-key",
"HTTP_PORT": "9274"
}
}
}
}
- 通过stdin/stdout进行MCP通信(由Claude Desktop管理)
- Web UI在单独的HTTP端口上运行(默认:9274,可自定义)
- 每个Claude Desktop实例都会生成自己的进程
- 非常适合本地开发和桌面使用
stdio模式下的自定义端口:
{
"env": {
"TRANSPORT": "stdio",
"AUTH_TOKEN": "your-api-key",
"HTTP_PORT": "3001"
}
}
HTTP模式(用于Claude Code和远程访问):
TRANSPORT=http mysql-mcp-webui
TRANSPORT=http HTTP_PORT=3001 mysql-mcp-webui
- 通过
/mcp 的HTTP端点进行MCP通信
- 支持多个并发会话且相互隔离
- 在同一端口上包含REST API和Web UI
- 非常适合远程访问、Docker部署和Claude Code
环境变量
| 变量 |
默认值 |
描述 |
TRANSPORT |
http |
传输模式:stdio 或 http |
HTTP_PORT |
9274 |
Web UI、API和MCP端点的端口(两种模式均可自定义) |
AUTH_TOKEN |
- |
API密钥(stdio模式必需) |
NODE_ENV |
development |
环境:development 或 production |
MCP_RESPONSE_FORMAT |
json |
MCP响应格式:json 或 toon(请参阅下面的 TOON格式) |
ENABLE_HTTPS |
false |
启用HTTPS/TLS |
SSL_CERT_PATH |
- |
SSL证书路径(启用HTTPS时必需) |
SSL_KEY_PATH |
- |
SSL私钥路径(启用HTTPS时必需) |
JWT_SECRET |
(自动生成) |
JWT令牌的密钥(开发环境可选,生产环境推荐) |
JWT_EXPIRES_IN |
7d |
JWT令牌过期时间(例如,1h、24h、7d、30d) |
RATE_LIMIT_ENABLED |
true |
启用速率限制 |
RATE_LIMIT_WINDOW_MS |
900000 |
速率限制窗口(毫秒)(15分钟) |
RATE_LIMIT_MAX_REQUESTS |
100 |
每个窗口的最大请求数 |
TOON格式(令牌优化)
MySQL MCP Server支持 TOON(面向令牌的对象表示法),这是一种优化后的格式,与JSON相比,向Claude返回查询结果时可减少约40%的令牌使用量。
何时使用TOON:
- 大型查询结果(100+行)
- 对令牌使用成本敏感的应用程序
- 最大化上下文窗口效率
如何启用:
对于Claude Desktop(stdio模式):
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "mysql-mcp-webui"],
"env": {
"TRANSPORT": "stdio",
"AUTH_TOKEN": "your-token",
"MCP_RESPONSE_FORMAT": "toon"
}
}
}
}
对于Claude Code / HTTP模式(通过每个客户端的头部):
{
"mcpServers": {
"mysql-web": {
"type": "http",
"url": "https://your-server-url.com/mcp",
"headers": {
"Authorization": "Bearer your-token",
"X-Response-Format": "toon"
}
}
}
}
对于Docker/HTTP模式(通过环境变量在服务器端全局设置):
docker run -d \
--name mysql-mcp \
-p 9274:9274 \
-e TRANSPORT=http \
-e MCP_RESPONSE_FORMAT=toon \
mysql-mcp-webui
HTTP模式的优先级顺序:
X-Response-Format 头部(每个客户端) - 推荐
MCP_RESPONSE_FORMAT 环境变量(服务器端全局设置)
- 默认:
json
示例对比:
标准JSON响应(冗长):
[
{ "id": 1, "name": "Alice", "email": "alice@example.com" },
{ "id": 2, "name": "Bob", "email": "bob@example.com" }
]
TOON格式(紧凑):
[2]{id,name,email}:
1,Alice,alice@example.com
2,Bob,bob@example.com
优点:
- ✅ 表格数据的令牌使用量减少约40%
- ✅ Claude对结构化数据的理解更好
- ✅ 明确的行数有助于大语言模型验证
- ✅ 在stdio和HTTP模式下均可使用
- ✅ HTTP模式:通过
X-Response-Format 头部为每个客户端进行配置(不同的Claude Code实例可以在同一服务器上使用不同的格式)
注意:TOON是可选的。默认的JSON格式适用于大多数用例。
了解有关TOON的更多信息:[github.com/toon - format/toon](https://github.com/toon - format/toon)
故障排除
MCP服务器因AUTH_TOKEN错误无法启动
症状:Claude Desktop日志显示 "AUTH_TOKEN environment variable is required" 或 "Invalid AUTH_TOKEN provided"
解决方案:
- 生成新的令牌(如果你还没有):
mysql-mcp-webui --generate-token
- 从输出中 复制生成的令牌。
- 使用新令牌 更新你的Claude Desktop配置 文件:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- 验证JSON语法 是否正确(无多余空格、引号或逗号)。
- 完全 重启Claude Desktop(退出并重新打开)。
注意:你必须在启动Claude Desktop之前生成令牌,而不是之后。
Claude无法连接到MCP服务器
- 检查Claude Desktop配置文件的语法(确保是有效的JSON格式)。
- 如果需要,生成新的API密钥:
mysql-mcp-webui --generate-token。
- 验证令牌是否正确粘贴到配置文件中。
- 完全重启Claude Desktop(退出并重新打开,而不仅仅是重新加载)。
- 检查Web UI是否可在 http://localhost:9274 访问。
权限被拒绝错误
- 打开Web UI → 数据库。
- 验证数据库是否启用了所需的权限。
- 检查数据库是否已启用(未禁用)。
- 确保MySQL用户具有实际的数据库权限。
连接错误
- 在Web UI中测试连接(连接页面 → 测试按钮)。
- 验证MySQL服务器是否正在运行且可访问。
- 检查防火墙规则。
- 确认MySQL凭据是否正确。
端口已被占用
HTTP_PORT=3001 mysql-mcp-webui
版本更新
v0.1.4版本新增内容
- 📦 官方TOON库 - 集成了官方
@toon - format/toon 库,用于正确处理嵌套数据
- 🏗️ 更好的嵌套结构 - 基于缩进的编码方式,用于正确处理嵌套对象和数组
- 🔄 智能格式化 - 自动检测格式以实现最佳表示(表格、列表或内联)
- ⚡ 提高效率 - 针对复杂的MySQL JSON列数据进行更好的令牌优化
- 🎯 点键折叠 - 单键链的紧凑表示(例如,
config.db.host: localhost)
- 🛠️ 维护良好的库 - 官方库确保持续符合规范并进行更新
之前的更新
v0.1.0:
- 🔧 新的MCP工具:add_connection - Claude现在可以通过编程方式创建MySQL连接
- 🏷️ 数据库别名 - 为数据库创建自定义、用户友好的名称
- 🎛️ 连接管理 - 启用/禁用连接以控制哪些连接处于活动状态
v0.0.7:
- 📖 增强的文档 - 新的以用户为中心的README,包含MCP工作流程示例
- 🔄 文档重组 - 技术细节移至README_DEVELOPMENT.md
资源
📄 许可证
本项目采用MIT许可证,请参阅 LICENSE 文件以获取详细信息。
致谢
准备好让Claude访问你的数据库了吗? 立即安装并开始使用自然语言探索你的数据吧!🚀