Mysql MCP Webui

🚀 MySQL MCP Server

通過模型上下文協議（MCP），讓Claude AI直接訪問你的MySQL數據庫。

MySQL MCP Server允許Claude Desktop和Claude Code執行SQL查詢、探索數據庫，並與你的MySQL數據進行交互——所有這些都通過一個安全的、可控制權限的接口實現。

🚀 快速開始

安裝

# 通過npm全局安裝
npm install -g mysql-mcp-webui

# 或者直接使用npx運行（無需安裝）
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

1. 保存 配置文件。
2. 完全 重啟Claude Desktop（退出並重新打開）。
3. Claude Desktop將自動啟動MCP服務器。
4. Web UI 可在 http://localhost:9274 訪問。

步驟4：配置MySQL連接

打開 http://localhost:9274 的Web UI：

1. 使用默認憑據 admin / admin 登錄。
   • 首次登錄時，系統會提示你更改密碼。
2. 添加MySQL連接：
   • 輸入你的MySQL服務器主機名、端口、用戶名和密碼。
   • 點擊“測試連接”以驗證連接是否正常。
3. 發現數據庫：
   • 點擊“發現數據庫”以自動檢測所有可用的數據庫。
4. 設置權限：
   • 對於每個數據庫，啟用Claude可以執行的操作。
   • 對於生產數據庫，建議從 僅允許SELECT 開始。
5. 設置默認連接（可選）：
   • 這將使啟動新的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

響應：[查詢結果以表格形式顯示]

執行過程：

1. Claude根據你的請求生成適當的SQL。
2. 根據數據庫權限驗證查詢（例如，必須具有SELECT權限）。
3. 在事務中執行查詢（出錯時自動回滾）。
4. 格式化結果以便於閱讀。

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

執行過程：

1. 列出你當前MySQL連接中的所有數據庫。
2. 顯示當前活動的數據庫。
3. 顯示每個數據庫的配置權限。
4. 可選地包含元數據（表數量、大小）。

3. switch_database - 更改活動數據庫

Claude可以使用數據庫別名在你的MySQL連接中切換數據庫。 示例對話：

你：“讓我們查看暫存數據庫”

Claude使用：switch_database
參數：{ database: "staging_db" }

響應：✓ 已從production_db切換到staging_db
權限：SELECT, INSERT, UPDATE, DELETE
你現在可以在staging_db中查詢數據並進行修改

執行過程：

1. 驗證數據庫是否存在於你的連接中。
2. 切換所有未來查詢的活動數據庫。
3. 返回新數據庫的權限。
4. 持久保存更改（重啟後仍然有效）。

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權限

執行過程：

1. 通過測試連接驗證連接憑據。
2. 在存儲之前使用AES - 256 - GCM加密密碼。
3. 將連接保存到數據庫。
4. 自動發現所有可用的數據庫。
5. 為發現的數據庫授予默認的SELECT權限。
6. 返回連接詳細信息和發現結果。

工作原理

┌─────────────────────────────────────────────────────┐
│  你：“顯示本月註冊的用戶”      │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│  Claude Desktop / Claude Code                       │
│  - 理解你的請求                         │
│  - 決定使用mysql_query工具                  │
│  - 生成適當的SQL                        │
└──────────────────┬──────────────────────────────────┘
                   │ MCP協議
┌──────────────────▼──────────────────────────────────┐
│  MySQL MCP Server                                   │
│  1. 驗證API令牌                             │
│  2. 檢查數據庫權限                     │
│  3. 解析SQL以驗證允許的操作         │
│  4. 在事務中執行查詢                   │
│  5. 返回結果                                 │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│  你的MySQL數據庫                                │
│  - 安全執行查詢                            │
│  - 返回結果                                 │
└─────────────────────────────────────────────────────┘

權限系統

每個數據庫都有細粒度的權限。你可以配置Claude可以執行的操作：

最佳實踐：對於生產數據庫，建議從 僅允許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注入

最佳實踐

1. 對於生產數據庫，最初使用 只讀權限。
2. 創建具有有限權限的專用MySQL用戶。
3. 通過Web UI 定期輪換API密鑰。
4. 查看審計日誌 以監控Claude對數據庫的訪問。
5. 僅啟用所需的數據庫 - 禁用其他數據庫。
6. 在生產環境中 使用HTTPS 進行遠程訪問。

多實例支持

安全地運行多個Claude Desktop實例或會話：

• stdio模式：每個Claude Desktop實例都有自己的進程
• HTTP模式：多個會話具有隔離的狀態
• 併發訪問：使用WAL模式安全地寫入SQLite
• 會話清理：自動清理非活動會話（30分鐘）

在Web UI中設置默認連接，以便所有新實例都以相同的設置啟動。

📦 安裝指南

安裝

# 通過npm全局安裝
npm install -g mysql-mcp-webui

# 或者直接使用npx運行（無需安裝）
npx mysql-mcp-webui

Claude Code（HTTP模式）設置指南

Claude Code可以通過HTTP模式連接到MySQL MCP Server，允許遠程訪問和多個併發會話。

選項1：使用npx（無需Docker）

步驟1：啟動服務器

# 在默認端口9274上以HTTP模式啟動
TRANSPORT=http npx -y mysql-mcp-webui

# 或者在自定義端口上啟動
TRANSPORT=http HTTP_PORT=3001 npx -y mysql-mcp-webui

步驟2：生成API令牌

打開 http://localhost:9274（或你的自定義端口）的Web UI：

1. 使用默認憑據 admin / admin 登錄。
2. 導航到 API密鑰 部分。
3. 點擊 生成新API密鑰。
4. 複製生成的密鑰。

步驟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部署

快速啟動（無需克隆）：

# 直接從基於npm的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（用於高級配置）：

# 僅在需要自定義docker-compose.yml時克隆
git clone https://github.com/yashagldit/mysql-mcp-webui.git
cd mysql-mcp-webui
cp .env.example .env
# 根據需要編輯.env文件（更改端口、啟用HTTPS等）
docker-compose up -d

步驟2：獲取API密鑰

# 訪問Web UI：http://localhost:9274
# 登錄：admin / admin
# 導航到API密鑰 → 生成新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進行以下操作：

1. 添加MySQL連接
2. 發現數據庫
3. 設置權限
4. 可選地設置默認連接

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

# 生成新的API令牌
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：

• 架構詳細信息
• API文檔
• 開發設置
• 貢獻指南

📚 詳細文檔

配置選項

傳輸模式

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和遠程訪問）：

# 在HTTP模式下啟動服務器（默認端口9274）
TRANSPORT=http mysql-mcp-webui

# 自定義端口
TRANSPORT=http HTTP_PORT=3001 mysql-mcp-webui

# MCP端點可在以下地址訪問：
# http://localhost:9274/mcp（或你的自定義端口）

• 通過 /mcp 的HTTP端點進行MCP通信
• 支持多個併發會話且相互隔離
• 在同一端口上包含REST API和Web UI
• 非常適合遠程訪問、Docker部署和Claude Code

環境變量

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模式的優先級順序：

1. X-Response-Format 頭部（每個客戶端） - 推薦
2. MCP_RESPONSE_FORMAT 環境變量（服務器端全局設置）
3. 默認：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"

解決方案：

1. 生成新的令牌（如果你還沒有）：

   mysql-mcp-webui --generate-token
   

2. 從輸出中 複製生成的令牌。
3. 使用新令牌 更新你的Claude Desktop配置 文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
4. 驗證JSON語法 是否正確（無多餘空格、引號或逗號）。
5. 完全 重啟Claude Desktop（退出並重新打開）。

注意：你必須在啟動Claude Desktop之前生成令牌，而不是之後。

Claude無法連接到MCP服務器

1. 檢查Claude Desktop配置文件的語法（確保是有效的JSON格式）。
2. 如果需要，生成新的API密鑰：mysql-mcp-webui --generate-token。
3. 驗證令牌是否正確粘貼到配置文件中。
4. 完全重啟Claude Desktop（退出並重新打開，而不僅僅是重新加載）。
5. 檢查Web UI是否可在 http://localhost:9274 訪問。

權限被拒絕錯誤

1. 打開Web UI → 數據庫。
2. 驗證數據庫是否啟用了所需的權限。
3. 檢查數據庫是否已啟用（未禁用）。
4. 確保MySQL用戶具有實際的數據庫權限。

連接錯誤

1. 在Web UI中測試連接（連接頁面 → 測試按鈕）。
2. 驗證MySQL服務器是否正在運行且可訪問。
3. 檢查防火牆規則。
4. 確認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

資源

• 文檔：GitHub倉庫
• 問題與支持：GitHub問題
• 模型上下文協議：modelcontextprotocol.io
• 開發指南：README_DEVELOPMENT.md
• 部署指南：DEPLOYMENT.md
• 更新日誌：CHANGELOG.md

📄 許可證

本項目採用MIT許可證，請參閱 LICENSE 文件以獲取詳細信息。

致謝

• 基於Anthropic的 模型上下文協議 構建。
• 為 Claude Desktop 和 Claude Code 提供支持。
• 由 Yash Agarwal 創建。

準備好讓Claude訪問你的數據庫了嗎？ 立即安裝並開始使用自然語言探索你的數據吧！🚀