Claude Media
Databricks MCPサーバーをClaude CodeにつないでSQLを実行する手順
ClaudeClaude CodeMCPClaude連携チュートリアル

Databricks MCPサーバーをClaude CodeにつないでSQLを実行する手順

Databricks SQLの新規接続はsystem.ai.dbsqlで、設定済みの/api/2.0/mcp/sqlはlegacyとして使えます。Claude Codeへの追加コマンドと、コミュニティ製2つとの使い分けを示します。

読了目安 約17分

Databricks SQLをClaude Codeから実行するなら、新規接続は公式のsystem.ai.dbsqlを使います。設定済みの/api/2.0/mcp/sqlは、legacyエンドポイントとしてそのまま使えます。追加コマンドは「公式Managed MCPにClaude Codeから接続する」の節にあります。

Claude CodeからDatabricksを触る道は、全部で3つあります。1つ目は、Databricksが運営する公式のManaged MCPサーバーです。2つ目は、SQL実行とジョブ確認に絞ったJordiNeil/mcp-databricks-serverです。3つ目は、Unity Catalogのリネージ探索まで持つRafaelCartenet/mcp-databricks-serverです。

「Databricks製は管理者の設定が重いので、手軽に試すならコミュニティ製」と考えがちです。ただ、選ぶ基準は認証の手軽さよりも、何をさせたいかと、誰の権限で動かすかです。

3つの選択肢はどういう状況で選び分けるか

選び方

状況別の選び先

  • 分析を任せたい → 公式のManaged MCP

    自然言語での分析ならGenie One、手書きSQLの検証ならDatabricks SQLサーバーです。サーバーはDatabricksが運用し、Unity Catalogの権限がそのまま効きます。

  • SQLとジョブ状況だけ見たい → JordiNeil版

    ツールは4つで、依存も少なめです。リポジトリの最終pushは2025年4月です。

  • テーブルの出自を追いたい → RafaelCartenet版

    カタログからテーブル、リネージ、ノートブックまで辿れます。最終pushは2026年3月で、3つの中では新しい側です。

Databricksのドキュメントは、分析用途ではまずGenie One MCPサーバーから始めるよう案内しています。Genieは「Genie Ontology」という管理されたセマンティックレイヤーで業務用語を解決するため、生のテーブルに対してエージェントがSQLを直接書くより正確になる、という説明です。Databricks SQLサーバーは、すでに書いたクエリの検証やパイプライン作成のような、特定のクエリを実行したいときの選択肢とされています。

コミュニティ製の2つはどちらも、エージェントがSQLを自分で組み立てる前提のツールです。Genieのような意味層は挟まりません。メタデータの質が低いワークスペースでは、ここで精度の差が出ます。

公式Managed MCPにClaude Codeから接続する

Databricksが用意するManaged MCPサーバーは、次の表の6種類です。system.aiのMCPサービスが新規接続の入口で、/api/2.0/mcp/で始まる4種はlegacyエンドポイントです。URLはワークスペースのホスト名を差し替えて使います。

Genie OneのMCPサービスsystem.ai.genie_one_mcpは一般提供(GA)です。system.ai.dbsqlを使うには、アカウント管理者がPreviewsページでUnity Gatewayのbetaを有効にします。legacyの4種は、ワークスペース管理者がPreviewsページでManaged MCP Serversを有効にしてから使います。各サーバーのリリース状況は、サーバーごとのページに載っています。以前のBetaエンドポイント/api/2.0/mcp/genieは、2026年10月31日に提供終了の予定です。旧エンドポイントで設定済みなら、移行が必要です。

サーバー用途URLパスOAuthスコープ
Genie One用途ワークスペース全体への自然言語分析URLパス/ai-gateway/mcp-services/system.ai.genie_one_mcpOAuthスコープai-gateway
Databricks SQL(新規接続)用途SQLウェアハウス上で特定のクエリを実行URLパス/ai-gateway/mcp-services/system.ai.dbsqlOAuthスコープai-gateway
Genie Agent(legacy)用途1つのGenie Agentに絞った分析URLパス/api/2.0/mcp/genie/{genie_space_id}OAuthスコープgenie
AI Search(legacy)用途非構造化ドキュメントの検索URLパス/api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name}OAuthスコープai-search
Databricks SQL(legacy)用途設定済み接続の開発者クエリ・データエンジニアリングURLパス/api/2.0/mcp/sqlOAuthスコープsql
Unity Catalog関数(legacy)用途定義済みSQLロジックをツール化URLパス/api/2.0/mcp/functions/{catalog}/{schema}/{function_name}OAuthスコープunity-catalog

legacyエンドポイントの認証は、OAuthとPATのどちらも使えます。ドキュメントの整理では、OAuthは本番利用やチーム利用向け、PATは個人の開発・テスト・短期利用向けです。PATを使うときは、有効期限をできるだけ短く設定し、トークンをソース管理や共有の設定ファイルに入れないよう求められています。

Claude Codeでは、リモートのHTTPサーバーを--transport httpで追加し、トークンを--headerで渡します。Databricksも、クライアントがカスタムヘッダーを受け付けるなら、PATをAuthorization: Bearer <トークン>で渡すよう案内しています。次は、設定済みのlegacy SQLエンドポイントに接続する例です。

claude mcp add --transport http databricks-sql \
  https://<ワークスペースのホスト名>/api/2.0/mcp/sql \
  --header "Authorization: Bearer <PAT>"

DatabricksのPATの例は、Cursor・Claude Desktop・Replit向けです。Claude Code向けの例は、OAuthとUnity GatewayのCLI(ug)だけです。ただ、ヘッダーで渡す方式はClaude Codeの--headerにそのまま対応します。

Databricksのドキュメントでは、PATは旧来(legacy)の認証方式の扱いです。Claude Codeなどのコーディングエージェントには、ugが最も簡単な方法と案内されています。

追加先のスコープは、既定のlocalだと自分専用で、トークンは~/.claude.jsonに保存されます。--scope projectにすると.mcp.jsonに書かれてリポジトリで共有する形になるため、PATを直接書いたままコミットしないよう注意してください。

Databricks SQLを新規につなぐ最短の経路は、Unity Gateway CLI(ug)でsystem.ai.dbsqlを追加する方法です。Databricks CLIのログインで認証するため、OAuthアプリもクライアントIDも要りません。前提として、アカウント管理者がUnity Gatewayのbetaを有効にしておきます。

ug mcp add --agents claude --names system.ai.dbsql
ug claude

--namesに渡すのは、Genie One(system.ai.genie_one_mcp)のようなMCPサービスの完全修飾名で、書式は<catalog>.<schema>.<service>です。/api/2.0/mcp/で始まるlegacyエンドポイントは、ugではなく上のPATか静的OAuthクライアントで追加します。

静的なOAuthクライアントを自分で設定する場合だけ、Databricksのアカウント管理者がOAuthアプリを作ります。Claude Codeでは、リダイレクトURLにhttp://localhost:8080/callbackを登録します。そのうえで、claude mcp add-jsonのoauthにclientIdとcallbackPortを渡します。claude mcp addの--client-id・--client-secret・--callback-portでも指定でき、--client-secretは値を取らず、マスク入力で聞かれます。Databricksはマネージドサーバーで動的クライアント登録(DCR)のOAuthフローに対応しないため、clientIdは省けません。

claude.aiのカスタムコネクタから使うなら、リダイレクトURLを2つ登録します。https://claude.ai/api/mcp/auth_callbackとhttps://claude.com/api/mcp/auth_callbackです。

ワークスペースにIPアクセスリストがある場合は、クライアントの送信元IPの許可が前提です。許可されていないと、認証の段階でワークスペース側に拒否されます。

料金は機能ごとに別の課金区分に乗ります。Unity Catalog関数はサーバーレス汎用コンピュートの料金です。Genie AgentとDatabricks SQLサーバーはDatabricks SQLの料金、AI SearchはAI Searchの料金です。

コミュニティ製Databricks MCPサーバー2つの違い

JordiNeil版とRafaelCartenet版は、どちらも個人開発者によるOSSです。GitHubスター数はJordiNeil版が50、RafaelCartenet版が43で、規模は近い水準です。星の数では決まらないので、設計の違いで選びます。

項目JordiNeil/mcp-databricks-serverRafaelCartenet/mcp-databricks-server
主目的JordiNeil/mcp-databricks-serverSQL実行とジョブ状態確認RafaelCartenet/mcp-databricks-serverUnity Catalogメタデータ探索とデータリネージ
主なツール数JordiNeil/mcp-databricks-server4種(run_sql_query等)RafaelCartenet/mcp-databricks-server5種(UC探索4種+SQL実行1種)
必要なPythonJordiNeil/mcp-databricks-server3.7以上RafaelCartenet/mcp-databricks-server3.10以上
認証JordiNeil/mcp-databricks-serverPAT + HTTP PathRafaelCartenet/mcp-databricks-serverPAT + SQL Warehouse ID
接続先の前提JordiNeil/mcp-databricks-serverSQL WarehouseRafaelCartenet/mcp-databricks-serverメタデータ探索はSDK経由、リネージとSQL実行はSQL Warehouse

JordiNeil版はSQL実行とジョブ確認に絞ったシンプルな実装です。RafaelCartenet版はカタログ・スキーマ・テーブルを探索し、テーブルの上流・下流の依存関係と、それを読み書きするノートブックやジョブまで辿れます。「とにかくSQLを投げたい」なら前者、「テーブルの出自から追いたい」なら後者です。

見落としやすいのは、RafaelCartenet版のSQL Warehouse IDの扱いです。READMEによると、DATABRICKS_SQL_WAREHOUSE_IDが主に必要になるのはリネージ取得とexecute_sql_queryのときだけです。カタログやテーブルの一覧・説明は、Databricks SDKのUnity Catalog APIで取るため、Warehouseが無くても動きます。

Claude Codeに追加する手順

どちらもPython実装で、stdioのローカルプロセスとして動きます。まず接続情報を.envに用意します。キー名が版で異なり、JordiNeil版はDATABRICKS_HTTP_PATH、RafaelCartenet版はDATABRICKS_SQL_WAREHOUSE_IDです。

DATABRICKS_HOST="your-instance.cloud.databricks.com"
DATABRICKS_TOKEN="your-personal-access-token"
DATABRICKS_HTTP_PATH="/sql/1.0/warehouses/your-warehouse-id"

JordiNeil版は、クローンして依存関係を入れ、接続テストを走らせるだけです。

git clone https://github.com/JordiNeil/mcp-databricks-server.git
cd mcp-databricks-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python test_connection.py

RafaelCartenet版は、uvでもpipでも依存関係を入れられます。READMEに書かれているのは、uvを使う場合は事前にインストールしておく、という前提です。

git clone https://github.com/RafaelCartenet/mcp-databricks-server.git
cd mcp-databricks-server
uv pip install -r requirements.txt

Claude Codeには、環境変数を-eで渡す形で追加します。--より後ろがサーバーを起動するコマンドです。

claude mcp add databricks \
  -e DATABRICKS_HOST=your-instance.cloud.databricks.com \
  -e DATABRICKS_TOKEN=your-personal-access-token \
  -e DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/your-warehouse-id \
  -- /path/to/mcp-databricks-server/.venv/bin/python /path/to/mcp-databricks-server/main.py

JSONで渡したいときはclaude mcp add-jsonで、.mcp.jsonにenvブロックを書く方法もあります。スコープの使い分けはClaude Code MCP設定ガイドにまとめています。Claude Desktopなら、claude_desktop_config.json(macOSは~/Library/Application Support/Claude/)のmcpServersに書きます。コミュニティ製は、commandとargsに加えて、環境変数をenvに入れます。

公式Managed MCPをPATで使う場合、Databricksのドキュメントにnpx mcp-remote <サーバーURL> --header "Authorization: Bearer <PAT>"の形の例があります。設定後はClaude Desktopを再起動します。ただしDatabricksは、PATを共有の設定ファイルに入れないよう求めています。

ジョブの状態を自然言語で確認する

JordiNeil版のlist_jobs・get_job_status・get_job_detailsは、Databricks Jobsの実行状況を会話から引けるようにします。

  • 「Databricksのジョブを一覧して」→ list_jobs()でワークスペース内のジョブ一覧を取得
  • 「ジョブID123の状態を教えて」→ get_job_status(job_id=123)で実行状態を確認
  • 「ジョブID456が失敗した原因を詳しく教えて」→ get_job_details(job_id=456)で詳細を取得

管理画面を開かなくても、Claude Codeの中でジョブの死活を確認できます。障害の一次切り分けに向いた使い方です。READMEのトークン権限には「クエリ実行とジョブへのアクセス権限」が前提として書かれているので、ジョブへのアクセス権が無いトークンでは、ジョブ情報を取得できません。

Unity Catalogのリネージ探索でできること

RafaelCartenet版のdescribe_uc_tableは、include_lineage=Trueを渡すと列の一覧を超えた情報を返します。上流・下流のテーブルに加え、そのテーブルを読み書きするノートブックの名前とワークスペース上のパス、紐づくジョブの名前・ID・タスクの詳細です。READMEは、ノートブックのパスが分かればエージェントが手元のリポジトリやワークスペースのファイルを直接読んで、変換ロジックやビジネスルールを解析できると説明しています。リネージの取得は時間がかかる場合があるとも書かれており、既定はFalseです。

手順

テーブルの出自を調べる流れ

  1. 1

    カタログを確認する

    list_uc_catalogs()で利用できるカタログを出します。

  2. 2

    スキーマを確認する

    describe_uc_catalog(catalog_name="prod")で、対象カタログのスキーマを見ます。

  3. 3

    テーブル構成を確認する

    describe_uc_schema(catalog_name="prod", schema_name="sales", include_columns=True)で、テーブルと列を見ます。

  4. 4

    リネージと処理コードの所在を特定する

    describe_uc_table(full_table_name="prod.sales.orders", include_lineage=True)で、依存関係とノートブックのパスを取得します。

  5. 5

    実際にクエリを実行する

    execute_sql_query(sql="...")で、探索で分かった内容を確かめます。

この流れは、Unity Catalogにカラムやテーブルの説明文を書き込んでいるほど効きます。READMEもこの前提で、サーバーが「Unity Catalogに書いた説明をLLMが読みやすい形に整えて渡す」ツールだと位置づけています。説明が空欄のままだと、Claudeが列の意味を推し量るしかなくなります。

RafaelCartenet版のREADMEは、メタデータを手作業で入れるより、Terraformなどでカタログやスキーマをコードとして管理する方法を勧めています。説明文をコードで持てば、変更履歴が残り、環境間で同じ内容を再現できるという趣旨です。

書き込みクエリを実行できてしまう範囲を権限で絞る

run_sql_query(JordiNeil版)とexecute_sql_query(RafaelCartenet版)は、渡されたSQL文字列を実行するツールです。RafaelCartenet版のREADMEは用途を「SELECT・SHOWなどのDQL」と説明していますが、ツール側で書き込み文を拒否するとは書いていません。execute_sql_queryの説明にも「任意のSQLクエリを実行する」とあり、ピンポイントの取得や複雑な操作に向くとされています。したがって、安全の担保はトークンの権限で作る前提で考えるのが堅実です。

RafaelCartenet版のREADMEは、トークンの持ち主(ユーザーまたはサービスプリンシパル)に必要な権限を具体的に挙げています。

  • カタログにUSE CATALOG、スキーマにUSE SCHEMA
  • 説明や列情報を取りたいテーブルにSELECT
  • DATABRICKS_SQL_WAREHOUSE_IDで指定したWarehouseにCAN_USE

加えて、本番や自動実行ではサービスプリンシパルを狭い権限で使うことを強く勧め、トークンのローテーションとクエリ履歴・Unity Catalog監査ログの確認も挙げています。JordiNeil版は「適切な権限スコープに限ったトークンを使う」「.envをバージョン管理に入れない」という書き方です。

公式Managed MCPでGenieを使うなら、基になるGenie Agentへのアクセスが要ります。system.aiのEXECUTEはアカウントユーザーに既定で付くため、追加の付与は通常要りません。

個人検証用のワークスペースを離れて本番データに接続するなら、書き込み権限を持たず、読み取りに必要な権限(USE CATALOG・USE SCHEMA・SELECT・CAN_USE)だけを付与したサービスプリンシパルのトークンという選択肢があります。ジョブ定義をファイルで書く側はClaude CodeでDatabricks Asset Bundlesを書くで扱っています。

databrickslabs/mcpを新規導入に選ばない理由

databrickslabs/mcpは、Unity Catalog向けサーバーなどを収めた実験的なMCPサーバー集です。スター数は97と、今回の2つより多いリポジトリです。ただしUnity Catalog向けサーバーには非推奨の注記があり、DatabricksはManaged MCPサーバーを推奨しています。

Databricks Labs配下のプロジェクトは、Databricksが正式にサポートするものではなく、SLAもありません。READMEはサポートチケットを出さず、GitHub Issuesに書くよう求めています。最終のpushは2025年7月です。星の数に引かれて新規に導入する理由は薄く、Managed MCPか、独立したコミュニティ実装かの二択で考えるのが実態に合います。

よくあるつまずき

  • DATABRICKS_HOSTにhttps://を含めてしまい接続できない: 両READMEとも、ホスト名はプレフィックスなし(your-instance.cloud.databricks.com)で渡す形です
  • SQL Warehouseが止まっていて応答しない: JordiNeil版のREADMEも、接続できないときはWarehouseが起動していてアクセスできるかを確認するよう案内しています
  • describe_uc_tableで列やリネージの詳細が取れない: READMEは、USE CATALOG・USE SCHEMA・SELECTを必要な権限として挙げています。トークンの持ち主の権限を先に確認します
  • 長いクエリの結果が返らない: RafaelCartenet版は、execute_sql_queryの待機上限を50秒に設定しています。上限を超えると、同期的な応答を得られない場合があります。範囲を絞ってから実行してください
  • 公式Managed MCPに届かない: 認証の段階で拒否されるときは、ワークスペースのIPアクセスリストで、クライアントの送信元IPが許可されているかを確認します

他のデータ基盤は、Claude Snowflake連携ガイドやClaude BigQuery連携も参考になります。

まとめ

分析ならまずGenie One、特定のクエリやリネージを辿りたいならコミュニティ製、という分け方になります。どの経路でも、トークンの持ち主の権限がそのまま実行範囲になるため、接続前に書き込み権限を持たないトークンへ絞っておくと安全です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude をもっと見る →