Databricks Sql MCP

🚀 Databricks SQL MCP Server

Model Context Protocol (MCP) サーバーで、Claude などの AI アシスタントが Databricks 上で SQL クエリを実行できるようになります。Claude はこのサーバーを Docker コンテナとして起動し、MCP の標準入出力トランスポートを使用して stdin/stdout を介して通信します。

✨ 主な機能

コアツール

• execute_sql - Databricks SQL Warehouse に対して任意の SQL クエリを実行します。
• list_databases - デフォルトのカタログ内のデータベース/スキーマを一覧表示します。
• list_tables - 特定のデータベース内のテーブルを一覧表示します。
• describe_table - テーブルの列名、型、コメントを表示します。

Unity Catalog ツール

• list_catalogs - Unity Catalog メタストア内のすべてのカタログを一覧表示します。
• list_schemas - 特定のカタログ内のスキーマを一覧表示します。
• list_tables_full - 完全な 3 パートの名前 (catalog.schema.table) を使用してテーブルを一覧表示します。
• describe_table_full - 完全なカタログパスを使用してテーブルを説明します。

Unity Catalog の階層構造

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

完全修飾名: catalog.schema.table (例: analytics.silver.customers)

📦 インストール前の準備

• Docker がインストールされ、実行中であること
• SQL Warehouse を持つ Databricks ワークスペースへのアクセス権があること
• Databricks の個人用アクセストークン
• Claude Desktop または Claude Code (CLI)

Databricks の認証情報の取得方法

1. Databricks のホスト URL

ワークスペースの URL です。形式はクラウドプロバイダーによって異なります。

2. 個人用アクセストークン

1. Databricks ワークスペースを開きます。
2. 右上のユーザー名をクリックします。
3. User Settings > Developer > Access tokens に移動します。
4. Generate new token をクリックします。
5. トークン ( dapi... で始まる) をコピーします。

3. SQL Warehouse ID

1. Databricks の SQL Warehouses に移動します。
2. ウェアハウスをクリックします。
3. URL からウェアハウス ID をコピーします: /sql/warehouses/<this-id>

🚀 クイックスタート (推奨)

インストールスクリプトは Docker イメージを取得し、Databricks の認証情報を入力するように促し、Claude Code CLI を使用して 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 とサーバー間の通信に stdin/stdout を使用します。

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 (CLI) の設定

Claude Code CLI を使用してサーバーを直接登録します:

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 に以下のようなクエリを投げることができます。

ブラウジング

• "List all catalogs in my Unity Catalog"
• "Show me the schemas in the analytics catalog"
• "What tables are in analytics.silver?"
• "Describe the schema of analytics.silver.customers"

クエリ実行

• "Run: SELECT * FROM analytics.silver.customers LIMIT 10"
• "Show me the top 5 most expensive items"
• "What's the total revenue by category?"

セキュリティに関する注意事項

.env ファイルや認証情報を Git にコミットしないでください！

• .env ファイルは .gitignore に記載されています。
• 各ユーザーは独自の Databricks 個人用アクセストークンを持っている必要があります。
• Docker イメージには認証情報は含まれていません。
• 認証情報は実行時に環境変数を介して渡されます。

開発

ローカル開発 (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"

• 3 つの環境変数すべてを渡したことを確認してください。
• .env ファイルに DATABRICKS_HOST、DATABRICKS_TOKEN、DATABRICKS_WAREHOUSE_ID の値が設定されていることを確認してください。

"Query failed: ..."

• 認証情報が正しいことを確認してください。
• SQL Warehouse が実行中であることを確認してください (自動停止されている可能性があります)。
• 要求されたデータにアクセスする権限があることを確認してください。

"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