Databricks Sql MCP

🚀 Databricks SQL MCP Server

Databricks SQL MCP Server是一個模型上下文協議（MCP）服務器，它允許像Claude這樣的AI助手在Databricks上執行SQL查詢。Claude將該服務器作為Docker容器啟動，並使用MCP標準輸入/輸出傳輸通過標準輸入/輸出來進行通信。

✨ 主要特性

核心工具

• execute_sql - 針對Databricks SQL數據倉庫運行任何SQL查詢
• list_databases - 列出默認目錄中的數據庫/模式
• list_tables - 列出特定數據庫中的表
• describe_table - 顯示錶的列名、類型和註釋

統一目錄工具

• list_catalogs - 列出統一目錄元數據存儲中的所有目錄
• list_schemas - 列出特定目錄中的模式
• list_tables_full - 使用完整的三部分命名（catalog.schema.table）列出表
• describe_table_full - 使用表的完整目錄路徑描述表

📚 詳細文檔

統一目錄層次結構

CATALOG (例如，analytics)
  └── SCHEMA/DATABASE (例如，silver)
      └── TABLE (例如，customers)

完全限定名稱：catalog.schema.table（例如，analytics.silver.customers）

📦 安裝指南

前提條件

• 已安裝並運行 Docker
• 具有SQL數據倉庫的 Databricks工作區 訪問權限
• Databricks個人訪問令牌
• Claude Desktop 或 Claude Code（命令行界面）

獲取Databricks憑證

1. Databricks主機URL

您的工作區URL。格式取決於您的雲提供商：

2. 個人訪問令牌

1. 打開您的Databricks工作區
2. 點擊您的用戶名（右上角）
3. 轉到 用戶設置 > 開發者 > 訪問令牌
4. 點擊 生成新令牌
5. 複製令牌（以 dapi... 開頭）

3. SQL數據倉庫ID

1. 轉到Databricks中的 SQL數據倉庫
2. 點擊一個數據倉庫
3. 從URL中複製數據倉庫ID：/sql/warehouses/<this-id>

快速安裝（推薦）

安裝腳本會拉取Docker鏡像，提示您輸入Databricks憑證，並使用Claude Code命令行界面將MCP服務器註冊到Claude。

Mac / Linux

curl -fsSL https://raw.githubusercontent.com/benguy1000/databricks-sql-mcp/master/install.sh | bash

或者先克隆倉庫：

git clone https://github.com/benguy1000/databricks-sql-mcp.git
cd databricks-sql-mcp
chmod +x install.sh
./install.sh

Windows (PowerShell)

git clone https://github.com/benguy1000/databricks-sql-mcp.git
cd databricks-sql-mcp
.\install.bat

運行安裝程序後，重啟Claude Desktop（或啟動新的Claude Code會話）即可開始使用。

手動安裝

如果您更喜歡手動設置，或者快速安裝不適合您的設置，請按照以下步驟操作。

使用Docker運行

從Docker Hub拉取鏡像

docker pull bkeeleygib/databricks-sql-mcp:latest

或者自己構建：

docker build -t bkeeleygib/databricks-sql-mcp .

使用環境變量運行

-i 標誌是必需的，因為MCP使用標準輸入/輸出在Claude和服務器之間進行通信。

docker run -i --rm \
  -e DATABRICKS_HOST="https://your-workspace.azuredatabricks.net" \
  -e DATABRICKS_TOKEN="dapi1234567890abcdef" \
  -e DATABRICKS_WAREHOUSE_ID="abc123def456" \
  bkeeleygib/databricks-sql-mcp:latest

使用.env文件運行

創建一個包含您的憑證的 .env 文件（請參閱 .env.example）：

DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
DATABRICKS_TOKEN=dapi1234567890abcdef
DATABRICKS_WAREHOUSE_ID=abc123def456

然後運行：

docker run -i --rm --env-file .env bkeeleygib/databricks-sql-mcp:latest

配置Claude Desktop

將服務器添加到您的Claude Desktop配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "databricks-sql": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "DATABRICKS_HOST=https://your-workspace.azuredatabricks.net",
        "-e", "DATABRICKS_TOKEN=dapi1234567890abcdef",
        "-e", "DATABRICKS_WAREHOUSE_ID=abc123def456",
        "bkeeleygib/databricks-sql-mcp:latest"
      ]
    }
  }
}

重要提示：將佔位符值替換為您的實際憑證，然後重啟Claude Desktop。

配置Claude Code（命令行界面）

使用Claude Code命令行界面直接註冊服務器：

claude mcp add-json databricks-sql '{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "DATABRICKS_HOST=https://your-workspace.azuredatabricks.net",
    "-e", "DATABRICKS_TOKEN=dapi1234567890abcdef",
    "-e", "DATABRICKS_WAREHOUSE_ID=abc123def456",
    "bkeeleygib/databricks-sql-mcp:latest"
  ]
}'

💻 使用示例

連接後，您可以向Claude詢問以下問題

瀏覽

• "列出我的統一目錄中的所有目錄"
• "顯示 analytics 目錄中的模式"
• "analytics.silver 中有哪些表？"
• "描述 analytics.silver.customers 的模式"

查詢

• "運行：SELECT * FROM analytics.silver.customers LIMIT 10"
• "顯示前5個最貴的商品"
• "按類別統計的總收益是多少？"

🔧 技術細節

開發

本地開發（不使用Docker）

需要 Python 3.11+。

# 安裝依賴項
pip install -r requirements.txt

# 創建包含您的憑證的.env文件
cp .env.example .env
# 使用您的值編輯.env

# 運行服務器
python server.py

項目結構

server.py          # MCP服務器實現（FastMCP + Databricks SDK）
requirements.txt   # Python依賴項（固定到主要版本）
Dockerfile         # Docker鏡像定義
install.sh         # Mac/Linux的快速安裝程序
install.bat        # Windows的快速安裝程序
.env.example       # 環境變量模板

故障排除

"Error: DATABRICKS_WAREHOUSE_ID not set"

• 確保您傳遞了所有三個環境變量
• 檢查您的 .env 文件中是否有 DATABRICKS_HOST、DATABRICKS_TOKEN 和 DATABRICKS_WAREHOUSE_ID 的值

"Query failed: ..."

• 驗證您的憑證是否正確
• 檢查SQL數據倉庫是否正在運行（它可能已自動掛起）
• 確保您有權限訪問請求的數據

"Server disconnected"

• 重啟Claude Desktop或啟動新的Claude Code會話
• 驗證Docker是否正在運行：docker info
• 檢查容器是否成功啟動：docker run -i --rm --env-file .env bkeeleygib/databricks-sql-mcp:latest

"Tables show as false"

• 此問題已在最新版本中修復
• 拉取最新鏡像：docker pull bkeeleygib/databricks-sql-mcp:latest

📄 許可證

MIT

⚠️ 重要提示

切勿將您的 .env 文件或憑證提交到Git！

💡 使用建議

• .env 文件已列入 .gitignore 中
• 每個用戶都需要自己的Databricks個人訪問令牌
• Docker鏡像不包含任何憑證
• 憑證在運行時通過環境變量傳遞