🚀 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訪問你的數據庫了嗎? 立即安裝並開始使用自然語言探索你的數據吧!🚀