Dbmcp

🚀 DBChat - 用人工智能與你的數據庫對話

DBChat 能將你的數據庫轉變為一個智能的對話夥伴。你可以用自然語言提問，即刻獲取答案，並創建精美的可視化圖表，這一切都能通過 Claude Desktop 實現。

🚀 快速開始

步驟 1：下載

從 GitHub Releases 下載最新版本：

• dbchat-2.0.4.jar - 基礎版本（支持 PostgreSQL、SQLite、H2、HSQLDB、CSV）
• dbchat-2.0.4.jar - 標準版本（新增 MySQL、MariaDB、ClickHouse）
• dbchat-2.0.4.jar - 企業版本（新增 Oracle、SQL Server、DB2）
• dbchat-2.0.4.jar - 包含所有數據庫支持（400MB+）

注意：你也可以僅構建包含所需驅動的自定義 JAR 文件。詳情請參閱 INSTALL.md。

重要提示：請確保你擁有使用所安裝的任何 JDBC 驅動的合法許可。DBChat 許可不涵蓋任何第三方代碼或二進制文件。

步驟 2：安裝 Claude Desktop（或其他 MCP 客戶端）

1. 下載 Claude Desktop（免費）
2. 使用你的 Claude 賬戶登錄
3. 重要：Claude 網站不支持 MCP。若要使用 Anthropic 模型的 MCP 功能，你需要使用 Claude Desktop。

步驟 3：設置數據庫連接

創建一個配置文件 dbchat.conf：

# 基本數據庫連接
DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

# 可選：啟用 Web 界面
HTTP_MODE=false
HTTP_PORT=8080

常見數據庫示例： MySQL：

DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

PostgreSQL：

DB_URL=jdbc:postgresql://localhost:5432/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=org.postgresql.Driver

SQLite：

DB_URL=jdbc:sqlite:/path/to/your/database.db
DB_USER=
DB_PASSWORD=
DB_DRIVER=org.sqlite.JDBC

使用 H2 進行測試（無需設置）：

DB_URL=jdbc:h2:mem:testdb
DB_USER=sa
DB_PASSWORD=
DB_DRIVER=org.h2.Driver

步驟 4：配置 Claude Desktop

1. 打開 Claude Desktop
2. 轉到 設置 → 開發者 → 編輯配置
3. 添加你的數據庫服務器：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", 
        "/absolute/path/to/dbchat-2.0.4.jar",
        "--config_file=/absolute/path/to/dbchat.conf"
      ]
    }
  }
}

不使用配置文件的替代方法：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:mysql://localhost:3306/your_database",
        "DB_USER": "your_username", 
        "DB_PASSWORD": "your_password",
        "DB_DRIVER": "com.mysql.cj.jdbc.Driver"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", 
        "C:/Users/YourName/Downloads/dbchat-2.0.4.jar",
        "--config_file=C:/Users/YourName/dbchat.conf"
      ]
    }
  }
}

注意：如果 Java 不在你的系統路徑中，請在命令中使用 Java（JDK 17+）的完整路徑。

步驟 5：連接多個數據庫

你可以同時使用多個數據庫！

{
  "mcpServers": {
    "production-db": {
      "command": "java",
      "args": ["-jar", "/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:mysql://prod-server:3306/production",
        "DB_USER": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "DB_DRIVER": "com.mysql.cj.jdbc.Driver",
        "SELECT_ONLY": "true"
      }
    },
    "analytics-db": {
      "command": "java", 
      "args": ["-jar", "/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:postgresql://analytics:5432/warehouse",
        "DB_USER": "analyst",
        "DB_PASSWORD": "password",
        "DB_DRIVER": "org.postgresql.Driver"
      }
    }
  }
}

步驟 6：重啟 Claude Desktop

關閉並重新打開 Claude Desktop。你應該會在聊天輸入框中看到數據庫連接指示器。

✨ 主要特性

🗣️ 自然語言數據庫查詢

• 用自然語言提問：例如 "上個月有多少客戶註冊？"
• 獲得對話式回應：Claude 會解釋數據並提供見解
• 無需 SQL 知識：非常適合業務用戶和分析師

📊 即時數據可視化

• 自動創建圖表：Claude 可以根據你的數據生成精美的圖表
• 多種圖表類型：支持折線圖、柱狀圖、餅圖、散點圖等
• 交互式洞察：可以通過後續問題深入挖掘數據

🔍 智能數據探索

• 數據庫發現：例如 "我們有哪些表？" "顯示客戶表的結構"
• 關係理解：Claude 會解釋表之間的關聯
• 數據質量洞察：可以發現重複數據、缺失數據和異常值

💼 輕鬆實現商業智能

• 高管儀表盤：例如 "為我們的董事會會議創建一份銷售摘要"
• 趨勢分析：例如 "顯示過去 6 個月的用戶增長情況"
• 績效指標：例如 "哪些產品表現不佳？"

📦 安裝指南

DBChat 幾乎可以與任何數據庫配合使用（只要該數據庫有 JDBC 驅動）。

常見數據庫

• MySQL / MariaDB - 適用於 Web 應用和電子商務
• Oracle - 適用於企業應用
• PostgreSQL - 適用於高級應用和分析
• SQL Server - 適用於微軟環境
• H2 - 用於測試和開發
• SQLite - 適用於本地應用和原型開發
• HSQLDB - 用於測試和開發

分析與雲數據庫

• Snowflake - 雲數據平臺
• Databricks - 雲數據平臺
• Amazon Redshift - AWS 數據倉庫
• Google BigQuery - 谷歌分析
• ClickHouse - 實時分析

基於平面文件的數據

• CSV 文件 - 電子表格數據和導出數據
• Excel 文件 - 可以導出為 CSV 格式並進行查詢

完整列表和構建選項請參閱 INSTALL.md。

💻 使用示例

基礎用法

"數據庫中有哪些表？"
"顯示客戶表的結構"
"每個表中有多少條記錄？"

高級用法

"計算每個客戶細分市場的客戶終身價值"
"識別我們銷售數據中的季節性趨勢"
"找出客戶年齡與購買行為之間的相關性"

📚 詳細文檔

更多實際示例

電子商務分析

"顯示從訪客到購買的轉化漏斗"
"哪些產品的退貨率最高？"
"創建一個顯示每日銷售業績的儀表盤"

客戶成功

"找出有流失風險的客戶"
"顯示客戶滿意度趨勢"
"確定我們最有價值的客戶細分市場"

財務報告

"生成本季度的損益表摘要"
"顯示過去 12 個月的現金流趨勢"
"按部門創建費用明細"

運營管理

"監控所有倉庫的庫存水平"
"顯示各承運商的運輸績效"
"找出我們訂單履行流程中的瓶頸"

數據可視化示例

DBChat 使 Claude 能夠直接從你的數據庫創建令人驚歎的可視化圖表：

銷售儀表盤

• 月收入趨勢：折線圖展示隨時間的增長情況
• 暢銷產品：柱狀圖顯示暢銷產品
• 區域績效：熱力圖展示各地區的銷售情況
• 客戶細分：餅圖展示收入分佈

分析報告

• 用戶增長：面積圖展示用戶獲取趨勢
• 績效指標：多軸圖表結合不同的關鍵績效指標
• 比較分析：並排可視化展示不同時期的數據

運營儀表盤

• 庫存水平：實時庫存可視化
• 系統性能：時間序列圖表展示關鍵指標
• 質量指標：統計圖表展示趨勢和異常值

🔧 技術細節

安全特性

只讀模式

通過只讀訪問保護你的數據：

SELECT_ONLY=true

查詢限制

控制資源使用：

MAX_ROWS_LIMIT=1000
QUERY_TIMEOUT_SECONDS=30
MAX_SQL_LENGTH=10000

本地處理

• 所有數據都保留在你的本地機器上
• 無需外部 API 調用
• 環境變量經過加密
• 本地通信安全可靠

網頁界面（可選）

啟用 HTTP 模式以實現基於 Web 的訪問：

# 開啟 HTTP 監聽器
HTTP_MODE=true
# 監聽端口 8080
HTTP_PORT=8080
# 綁定到所有接口（允許外部訪問）
BIND_ADDRESS=0.0.0.0
# 注意：如果未指定綁定地址，默認綁定到本地主機（最安全）

然後通過 http://localhost:8080/ 進行訪問。例如，嘗試 http://localhost:8080/health 來檢查健康狀態。

若要通過 CLI 參數進行類似配置，請使用：

# 僅綁定到本地主機（默認，最安全）
java -jar dbchat-2.0.4.jar --http_mode=true --http_port=8080

# 綁定到所有接口（允許外部訪問）
java -jar dbchat-2.0.4.jar --http_mode=true --bind_address=0.0.0.0 --http_port=8080

# 綁定到特定接口
java -jar dbchat-2.0.4.jar --http_mode=true --bind_address=192.168.1.100 --http_port=8080

配置方法和優先級

為了實現最大的靈活性，DBChat 支持多種配置方法，如 CLI 參數、配置文件、環境變量、系統屬性和內置默認值。瞭解優先級順序對於故障排除和高級設置至關重要。

配置優先級順序（從高到低）

1. 命令行參數（最高優先級）
2. 配置文件
3. 環境變量
4. 系統屬性
5. 內置默認值（最低優先級）

這意味著命令行參數將始終覆蓋配置文件，配置文件將覆蓋環境變量，依此類推。

方法 1：命令行參數

格式：--parameter_name=value 使用場景：快速覆蓋、測試、一次性配置

java -jar dbchat-2.0.4.jar \
  --db_url="jdbc:mysql://localhost:3306/mydb" \
  --db_user="username" \
  --db_password="password" \
  --db_driver="com.mysql.cj.jdbc.Driver" \
  --http_mode=true \
  --http_port=8080 \
  --select_only=true

可用參數：

• --config_file=/path/to/config.conf
• --db_url="jdbc:..."
• --db_user="username"
• --db_password="password"
• --db_driver="com.mysql.cj.jdbc.Driver"
• --http_mode=true
• --http_port=8080
• --max_connections=20
• --connection_timeout_ms=30000
• --query_timeout_seconds=60
• --select_only=true
• --max_sql_length=50000
• --max_rows_limit=10000

方法 2：配置文件

格式：KEY=VALUE（每行一個） 使用場景：生產環境、複雜配置、版本控制

創建一個文件（例如 dbchat.conf）：

# 數據庫連接
DB_URL=jdbc:postgresql://localhost:5432/myapp
DB_USER=dbuser
DB_PASSWORD=my secure password with spaces
DB_DRIVER=org.postgresql.Driver

# 連接池設置
MAX_CONNECTIONS=20
CONNECTION_TIMEOUT_MS=60000
IDLE_TIMEOUT_MS=300000
MAX_LIFETIME_MS=1800000
LEAK_DETECTION_THRESHOLD_MS=60000

# 查詢設置
QUERY_TIMEOUT_SECONDS=45
SELECT_ONLY=false
MAX_SQL_LENGTH=50000
MAX_ROWS_LIMIT=50000

# 服務器設置
HTTP_MODE=true
HTTP_PORT=8080

使用方法：

java -jar dbchat-2.0.4.jar --config_file=dbchat.conf

配置文件特性：

• 註釋以 # 開頭
• 空行將被忽略
• 值可以加引號：DB_PASSWORD="password with spaces"
• 鍵不區分大小寫
• 支持與命令行相同的所有參數

方法 3：環境變量

格式：UPPERCASE_WITH_UNDERSCORES 使用場景：Docker、雲部署、CI/CD、安全憑證管理

export DB_URL="jdbc:mysql://localhost:3306/mydb"
export DB_USER="username"
export DB_PASSWORD="password"
export DB_DRIVER="com.mysql.cj.jdbc.Driver"
export HTTP_MODE="true"
export HTTP_PORT="8080"
export SELECT_ONLY="true"

java -jar dbchat-2.0.4.jar

所有環境變量：

• CONFIG_FILE - 配置文件的路徑
• DB_URL - 數據庫連接 URL
• DB_USER - 數據庫用戶名
• DB_PASSWORD - 數據庫密碼
• DB_DRIVER - JDBC 驅動類
• HTTP_MODE - 啟用 HTTP 模式（true/false）
• HTTP_PORT - HTTP 服務器端口
• MAX_CONNECTIONS - 連接池大小
• CONNECTION_TIMEOUT_MS - 連接超時時間
• QUERY_TIMEOUT_SECONDS - 查詢超時時間
• SELECT_ONLY - 只讀模式（true/false）
• MAX_SQL_LENGTH - 最大查詢長度
• MAX_ROWS_LIMIT - 最大結果行數
• IDLE_TIMEOUT_MS - 連接空閒超時時間
• MAX_LIFETIME_MS - 連接最大生命週期
• LEAK_DETECTION_THRESHOLD_MS - 洩漏檢測閾值

方法 4：系統屬性

格式：-Dparameter.name=value（下劃線變為點） 使用場景：JVM 特定配置、IDE 運行配置

java -Ddb.url="jdbc:mysql://localhost:3306/mydb" \
     -Ddb.user="username" \
     -Ddb.password="password" \
     -Ddb.driver="com.mysql.cj.jdbc.Driver" \
     -Dhttp.mode="true" \
     -Dhttp.port="8080" \
     -jar dbchat-2.0.4.jar

屬性命名：環境變量 DB_URL 對應的系統屬性為 db.url

方法 5：內置默認值

適用情況：未提供配置時 值：為開發提供安全的默認值

DB_URL=jdbc:h2:mem:testdb
DB_USER=sa
DB_PASSWORD=
DB_DRIVER=org.h2.Driver
HTTP_MODE=false
HTTP_PORT=8080
MAX_CONNECTIONS=10
CONNECTION_TIMEOUT_MS=30000
QUERY_TIMEOUT_SECONDS=30
SELECT_ONLY=true
MAX_SQL_LENGTH=10000
MAX_ROWS_LIMIT=10000

配置示例

示例 1：優先級覆蓋

# 配置文件中設置 HTTP_PORT=8080
echo "HTTP_PORT=8080" > config.conf

# 環境變量設置不同的端口
export HTTP_PORT=9090

# 命令行參數覆蓋兩者
java -jar dbchat-2.0.4.jar --config_file=config.conf --http_port=7070

# 結果：使用端口 7070（命令行參數優先級最高）

示例 2：混合配置

# 使用配置文件設置數據庫相關設置
echo "DB_URL=jdbc:mysql://localhost:3306/mydb" > prod.conf
echo "DB_USER=produser" >> prod.conf
echo "SELECT_ONLY=true" >> prod.conf

# 通過環境變量覆蓋密碼（更安全）
export DB_PASSWORD="secure_password"

# 通過命令行參數覆蓋端口（僅本次運行有效）
java -jar dbchat-2.0.4.jar --config_file=prod.conf --http_port=9090

示例 3：Claude Desktop 配置

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", "/path/to/dbchat-2.0.4.jar",
        "--config_file=/path/to/production.conf",
        "--select_only=true"
      ],
      "env": {
        "DB_PASSWORD": "secure_password_from_env"
      }
    }
  }
}

配置參數參考

數據庫連接

• DB_URL - JDBC 連接字符串（必需）
• DB_USER - 數據庫用戶名
• DB_PASSWORD - 數據庫密碼
• DB_DRIVER - JDBC 驅動類（必需）

連接池

• MAX_CONNECTIONS=10 - 最大併發連接數
• CONNECTION_TIMEOUT_MS=30000 - 連接獲取超時時間
• IDLE_TIMEOUT_MS=600000 - 連接空閒超時時間（10 分鐘）
• MAX_LIFETIME_MS=1800000 - 連接最大生命週期（30 分鐘）
• LEAK_DETECTION_THRESHOLD_MS=60000 - 連接洩漏檢測（1 分鐘）

查詢設置

• QUERY_TIMEOUT_SECONDS=30 - SQL 查詢執行超時時間
• SELECT_ONLY=true - 只讀模式（阻止 INSERT/UPDATE/DELETE 操作）
• MAX_SQL_LENGTH=10000 - SQL 查詢的最大字符數
• MAX_ROWS_LIMIT=10000 - 每個查詢返回的最大行數

服務器設置

• HTTP_MODE=false - 啟用 HTTP Web 界面
• HTTP_PORT=8080 - HTTP 服務器端口

安全最佳實踐

憑證管理

# 推薦：使用環境變量存儲密碼
export DB_PASSWORD="secure_password"
java -jar dbchat-2.0.4.jar --config_file=app.conf

# 推薦：使用具有受限權限的配置文件
chmod 600 secure.conf
java -jar dbchat-2.0.4.jar --config_file=secure.conf

# 避免：在命令行中明文顯示密碼（會在進程列表中可見）
java -jar dbchat-2.0.4.jar --db_password="visible_password"

配置文件安全

# 創建安全的配置文件
umask 077
cat > secure.conf << EOF
DB_PASSWORD=secure_password
EOF

# 驗證權限
ls -la secure.conf
# 應該顯示：-rw-------（僅所有者可讀寫）

配置故障排除

檢查有效配置

啟用調試日誌以查看實際使用的值：

java -Dlogging.level.root=DEBUG -jar dbchat-2.0.4.jar --config_file=myconfig.conf

常見問題

1. 找不到配置文件：使用絕對路徑
2. 權限被拒絕：檢查文件權限
3. 使用了錯誤的值：檢查優先級順序
4. 環境變量未設置：使用 env | grep DB_ 進行驗證

驗證命令

# 使用當前配置測試數據庫連接
java -jar dbchat-2.0.4.jar --help

# 驗證配置文件語法
grep -v "^#" myconfig.conf | grep -v "^$"

# 檢查環境變量
env | grep -E "(DB_|HTTP_|MAX_|SELECT_)"

🚫 故障排除

Claude Desktop 無法連接

1. 檢查路徑：在配置中使用絕對路徑
2. Java 版本：確保安裝了 Java 17 或更高版本
3. 文件權限：驗證 JAR 文件是否可讀
4. 重啟 Claude：關閉並重新打開 Claude Desktop

數據庫連接問題

1. 測試連接：驗證數據庫是否正在運行
2. 檢查憑證：確保用戶名和密碼正確
3. 網絡訪問：確認數據庫允許連接
4. 驅動支持：使用適合你數據庫的正確 JAR 版本

性能問題

1. 限制結果：使用 MAX_ROWS_LIMIT=1000
2. 查詢超時：設置 QUERY_TIMEOUT_SECONDS=30
3. 連接池：調整 MAX_CONNECTIONS=10

常見錯誤消息

"ClassNotFoundException"

• 下載適合你數據庫的正確 JAR 版本
• 檢查數據庫驅動是否已包含

"Connection refused"

• 驗證數據庫服務器是否正在運行
• 檢查連接 URL、用戶名和密碼
• 確保數據庫允許從你的機器進行連接

"Server not responding"

• 檢查 Claude Desktop 的配置語法
• 驗證 Java 是否在系統路徑中可用
• 查看 Claude Desktop 的日誌

🎯 最佳實踐

入門建議

1. 從只讀模式開始：最初使用 SELECT_ONLY=true
2. 使用示例數據進行測試：可以先嚐試使用 H2 數據庫
3. 從簡單問題開始：從基本的表探索開始
4. 逐步增加複雜度：隨著時間推移，逐漸轉向高級分析

安全方面

1. 使用專用數據庫用戶：為 DBChat 創建只讀用戶
2. 限制訪問權限：僅授予必要的表權限
3. 監控使用情況：定期審查查詢日誌
4. 備份數據：始終維護數據庫備份

性能方面

1. 設置合理的限制：使用 MAX_ROWS_LIMIT 和超時設置
2. 對重要列創建索引：確保查詢能夠高效運行
3. 監控資源使用：關注 CPU 和內存使用情況
4. 優化查詢：讓 Claude 建議查詢優化方案

📚 瞭解更多

• 模型上下文協議：modelcontextprotocol.io
• Claude Desktop：claude.ai/download
• 開發者指南：有關技術細節，請參閱 INSTALL.md
• GitHub 倉庫：github.com/skanga/dbchat

🚀 準備好改變你的數據體驗了嗎？

1. 下載 適合你數據庫的 JAR 文件
2. 安裝 Claude Desktop（免費）
3. 配置 你的數據庫連接
4. 添加 DBChat 到 Claude Desktop 設置中
5. 開始 詢問關於你數據的問題！

改變你與數據的交互方式。無需再編寫複雜的 SQL 查詢，無需再等待報告。只需通過自然語言與你的數據庫對話，藉助 Claude 的智能和 DBChat 的無縫集成。

立即開始，發現你的數據想要告訴你的信息。