Databricks MCP Server

Databricks MCP Server

• 動機
• 概要
• AI エージェントにとっての UC メタデータの実用的なメリット
• 利用可能なツールと機能
• セットアップ
  • システム要件
  • インストール
• 権限要件
• サーバーの実行
  • スタンドアロンモード
  • Cursor での使用
• 使用ワークフローの例（LLM エージェント向け）
• Terraform によるコードとしてのメタデータ管理
• 長時間実行されるクエリへの対応
• 依存関係

動機

Databricks Unity Catalog（UC）では、カタログ、スキーマ、テーブル、カラムなどのデータ資産について詳細にドキュメント化できます。これらの資産を十分にドキュメント化するには、時間をかける必要があります。よくある疑問は、メタデータを詳細に記録することで、実際にどのようなメリットが得られるのかということです。

この MCP サーバーは、その取り組みに確かな意義をもたらします。LLM が Unity Catalog のメタデータに直接アクセスし、活用できるようにします。UC 内のデータが詳細に記述されているほど、LLM エージェントは Databricks 環境をより効果的に理解できます。この深い理解は、データリクエストに応えるため、エージェントがよりインテリジェントで正確な SQL クエリを自律的に構築するうえで重要です。

概要

この Model Context Protocol（MCP）サーバーは、Databricks と連携するように設計されており、Unity Catalog（UC）メタデータの活用と、包括的なデータリネージの調査に重点を置いています。主な目的は、AI エージェントに包括的なツール一式を提供し、データに関する質問へ自力で回答できるようにすることです。エージェントは UC を自律的に調査し、データ構造を理解し、データリネージ（ノートブックやジョブの依存関係を含む）を分析し、SQL クエリを実行することで、各ステップで人が直接介入することなくデータリクエストに応えられます。

従来のカタログ閲覧に加えて、このサーバーを使うと、エージェントはデータを処理する実際のコードを検出して分析できます。拡張されたリネージ機能により、エージェントはテーブルから読み取る、またはテーブルに書き込むノートブックやジョブを特定し、それらのノートブックに実装された実際の変換ロジック、ビジネスルール、データ品質チェックを調べられます。これにより、エージェントは存在するデータが「何か」だけでなく、「どのように」処理・変換されるのかも理解できる、強力なフィードバックループが実現します。

エージェントモードで使用すると、複数のリクエストを反復的に処理し、データの検出、影響分析、コードの調査などの複雑なタスクを実行できます。

AI エージェントにとっての UC メタデータの実用的なメリット

この MCP サーバーが提供するツールは、Unity Catalog に追加した説明を解析して提示するとともに、データ処理コードを詳しく調査できるように設計されています。これにより、LLM ベースのエージェントに具体的なメリットがもたらされ、有用な SQL を生成する能力やデータエコシステムを理解する能力に直接影響します。

• データコンテキストの明確化：エージェントはテーブルや列の用途をすばやく理解できるため、曖昧さが軽減されます。この基礎的な理解が、正しいクエリを組み立てるための第一歩です。
• クエリ生成の精度向上：説明、データ型、リレーションシップにアクセスすることで、エージェントはより高い精度と意味的な正確さを備えた SQL クエリを作成できます。
• クエリ計画に向けた効率的なデータ探索：メタデータによって、エージェントはカタログやスキーマをより効率的にたどり、SQL クエリに含めるべきテーブルや列を特定できます。
• 包括的なデータリネージ：テーブル間の関係だけでなく、データを処理するノートブックやジョブもエージェントが検出できるため、影響分析やデータパイプラインの問題のデバッグが可能になります。
• コードレベルの理解：ノートブックの内容を調査することで、エージェントは実際の変換ロジック、ビジネスルール、データ品質チェックを分析でき、データの処理方法や変換方法についてより深く把握できます。
• エンドツーエンドのデータフロー分析：エージェントは、生データの取り込みから変換パイプラインを経て最終的な利用に至るまでデータを追跡し、各段階の構造と処理ロジックの両方を理解できます。

このサーバーを介して Unity Catalog の適切に文書化されたメタデータにアクセスすると、LLM エージェントはより多くの情報に基づいて動作し、より適切な判断を下せるようになり、結果としてより効果的な SQL クエリを生成できます。たとえば、スキーマの説明は、クエリに関連するデータソースをエージェントが特定するのに役立ちます。

図 1：ユーザーが説明を追加した Unity Catalog のスキーマ。この MCP サーバーはこの情報を LLM から直接利用できるようにし、クエリ戦略の決定に役立てます。

同様に、列レベルの詳細なコメントは各フィールドの意味を明確にします。これは、正確な SQL の条件や選択項目を組み立てるうえで重要です。

図 2：Unity Catalog の列レベルの説明。これらの詳細は LLM に渡され、データ構造の理解を助け、正確な SQL 生成に役立ちます。

利用可能なツールと機能

この MCP サーバーは、Databricks を利用する LLM エージェントを支援するためのツール一式を提供します。

主な機能：

• SQL クエリの実行：execute_sql_query(sql: str) ツールを使って、Databricks SDK 経由で任意の SQL クエリを実行します。対象を絞ったデータ取得や複雑な操作に適しています。
• LLM に適した出力：説明を返すすべてのツールは、LLM が利用しやすい Markdown 形式で情報を返すため、エージェントがコンテキストを解析して理解しやすくなります。

Unity Catalog の探索ツール：

サーバーは、Unity Catalog のアセットをたどって理解するための次のツールを提供します。これらは、クエリの作成や判断を行う前に、エージェント的な方法で LLM エージェントがコンテキストを収集するために設計されています。

1. list_uc_catalogs() -> str

   • 説明：利用可能なすべての Unity Catalog の名前、説明、タイプを一覧表示します。
   • 使用するタイミング：具体的なカタログ名が分からない場合に、利用可能なデータソースを見つける出発点として使用します。ワークスペースでアクセス可能なすべてのカタログの概要を確認できます。

2. describe_uc_catalog(catalog_name: str) -> str

   • 説明：特定の Unity Catalog の概要を提供し、名前と説明を含むすべてのスキーマを一覧表示します。
   • 使用する場面：カタログ名がわかっており、その中のスキーマを確認する必要がある場合に使用します。特定のスキーマやテーブルの詳細を確認する前段階として利用することがよくあります。
   • 引数：
     • catalog_name：説明する Unity Catalog の名前（例：prod、dev、system）。

3. describe_uc_schema(catalog_name: str, schema_name: str, include_columns: Optional[bool] = False) -> str

   • 説明：Unity Catalog 内の特定のスキーマについて、詳細な情報を提供します。スキーマ内のすべてのテーブルを返し、必要に応じて各テーブルの列の詳細も含めます。
   • 使用する場面：主にテーブルなど、スキーマの内容を把握する場合に使用します。列の情報を取得するには include_columns=True に設定します。これはクエリの作成に不可欠ですが、出力が長くなります。include_columns=False の場合は、テーブル名と説明のみが表示されるため、概要をすばやく確認できます。
   • 引数：
     • catalog_name：スキーマを含むカタログの名前。
     • schema_name：説明するスキーマの名前。
     • include_columns：True の場合、列とともにテーブルを一覧表示します。簡潔な概要を表示するため、デフォルトは False です。

4. describe_uc_table(full_table_name: str, include_lineage: Optional[bool] = False) -> str

   • 説明：包括的なリネージ機能を備え、Unity Catalog の特定のテーブルについて詳細な説明を提供します。
   • 使用する場面：単一のテーブルの構造（列、データ型、パーティション分割）を把握する場合に使用します。そのテーブルに対する SQL クエリを作成する前に、必ず確認してください。必要に応じて、従来のテーブル間の依存関係を超える包括的なリネージ情報も含められます。
     • テーブルのリネージ：上流テーブル（このテーブルが読み取るテーブル）と下流テーブル（このテーブルを読み取るテーブル）
     • ノートブックとジョブのリネージ：このテーブルの読み取りまたは書き込みを行うノートブック。ノートブック名、ワークスペースのパス、関連する Databricks ジョブ情報（ジョブ名、ID、タスクの詳細）が含まれます
     • コードの探索：リネージによってノートブックのパスが提供されるため、エージェントは現在のリポジトリ／ワークスペース内のノートブックファイルを直接読み取り、実際のデータ変換ロジックを分析できます
   • 引数：
     • full_table_name：テーブルの完全修飾された3部構成の名前（例：catalog.schema.table）。
     • include_lineage：包括的なリネージ（テーブル、ノートブック、ジョブ）を取得するには True に設定します。デフォルトは False です。取得に時間がかかる場合がありますが、データ依存関係を把握し、コードを探索するための豊富なコンテキストが得られます。

5. execute_sql_query(sql: str) -> str

   • 注：これは「Core Capabilities」に記載されているものと同じツールですが、UC の探索後にクエリを実行する一般的なエージェントのワークフローに関連して、ここでも説明しています。
   • 説明：指定された SQL クエリを Databricks SQL warehouse に対して実行し、整形された結果を返します。
   • 使用する場面：SELECT、SHOW、その他の DQL 文など、特定の SQL クエリを実行する必要がある場合に使用します。
   • 引数：
     • sql：実行する完全な SQL クエリ文字列。

セットアップ

システム要件

• Python 3.10+
• uv を使用してインストールする場合は、インストール済みであることを確認してください

インストール

1. 必要な依存関係をインストールします。

pip install -r requirements.txt

または、uv を使用する場合：

uv pip install -r requirements.txt

2. 環境変数を設定します。

   オプション 1：.env ファイルを使用する（推奨）

   このプロジェクトのルートディレクトリに .env ファイルを作成し、Databricks の認証情報を設定します。

   DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com"
   DATABRICKS_TOKEN="your-databricks-personal-access-token"
   DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"
   

   オプション 2：環境変数を直接設定する

   export DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com"
   export DATABRICKS_TOKEN="your-databricks-personal-access-token"
   export DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"
   

   SQL ウェアハウス ID は、Databricks UI の「SQL Warehouses」で確認できます。 DATABRICKS_SQL_WAREHOUSE_ID は主に、テーブルのリネージの取得と execute_sql_query ツールによる SQL クエリの実行に使用されます。 メタデータの参照ツール（カタログ、スキーマ、テーブルの一覧表示や説明）では、Databricks SDK の一般的な UC API を使用するため、リネージを要求しない限り SQL ウェアハウス ID は必須ではありません。

必要な権限

この MCP サーバーを使用する前に、DATABRICKS_TOKEN に関連付けられた ID（ユーザーまたはサービスプリンシパルなど）に、必要な権限があることを確認してください。

1. Unity Catalog の権限：
   • アクセスするカタログに対する USE CATALOG。
   • アクセスするスキーマに対する USE SCHEMA。
   • クエリを実行するテーブル、または詳細情報（列情報を含む）を確認するテーブルに対する SELECT。
   • すべてのカタログを一覧表示するには、メタストアレベルの適切な権限が必要な場合があります。そうでない場合は、ユーザーが少なくとも USE CATALOG 権限を持つカタログが一覧表示されます。
2. SQL ウェアハウスの権限（execute_sql_query とリネージの取得に必要）：
   • DATABRICKS_SQL_WAREHOUSE_ID で指定した SQL ウェアハウスに対する CAN_USE 権限。
3. トークンの権限：
   • 個人用アクセストークンまたはサービスプリンシパルのトークンには、必要最小限のスコープを設定してください。Unity Catalog の操作では、通常、ワークスペースへのアクセス権限が必要です。SQL の実行では、SQL の権限が必要です。
   • 本番環境や自動化されたシナリオでは、権限を限定したサービスプリンシパルを使用することを強く推奨します。

セキュリティのベストプラクティスとして、アクセストークンを定期的にローテーションし、クエリ履歴と UC の監査ログを監査して使用状況を監視することを検討してください。

サーバーの実行

スタンドアロンモード

サーバーをスタンドアロンモード（Agent Composer でのテストなど）で実行するには：

python main.py

これにより、stdio トランスポートを使用して MCP サーバーが起動します。このサーバーは Agent Composer やその他の MCP クライアントで使用できます。

Cursor での使用

この MCP サーバーを Cursor で使用するには、Cursor の設定（~/.cursor/mcp.json）で構成します。

1. ホームディレクトリに .cursor ディレクトリがまだない場合は作成します
2. そのディレクトリに mcp.json ファイルを作成するか、編集します。

mkdir -p ~/.cursor
touch ~/.cursor/mcp.json

3. 以下の設定を mcp.json ファイルに追加し、ディレクトリパスをこのサーバーをインストールした実際のパスに置き換えます。

{
    "mcpServers": {
        "databricks": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/mcp-databricks-server",
                "run",
                "main.py"
            ]
        }
    }
}

python を使用する例：

{
    "mcpServers": {
        "databricks": {
            "command": "python",
            "args": [
                "/path/to/your/mcp-databricks-server/main.py"
            ]
        }
    }
}

変更を適用するには Cursor を再起動してください。再起動後、Cursor で databricks エージェントを使用できます。

使用ワークフローの例（LLM エージェント向け）

この MCP サーバーを使うと、LLM エージェントが Databricks 環境を自律的に探索できます。次のスクリーンショットは、エージェントがスキーマやテーブルを繰り返し探索し、最初のクエリで結果が得られない場合もアプローチを調整しながら、要求されたデータの取得に成功するまでの一般的なやり取りを示しています。

図3：Databricks MCP ツールを使用する LLM エージェントが、特定のページビューのデータを探すために、繰り返し探索し、クエリを調整する様子を示しています。

エージェントは、次のようなワークフローに従う場合があります。

1. 利用可能なカタログを確認する：list_uc_catalogs()
   • エージェントは一覧から prod_catalog が関連すると判断します。
2. 特定のカタログを探索する：describe_uc_catalog(catalog_name="prod_catalog")
   • エージェントは sales_schema と inventory_schema を確認します。
3. 特定のスキーマを探索する（概要表示）：describe_uc_schema(catalog_name="prod_catalog", schema_name="sales_schema")
   • エージェントは orders や customers などのテーブル名を確認します。
4. テーブル構造の詳細を取得する（クエリ作成に必要な列を含む）：describe_uc_schema(catalog_name="prod_catalog", schema_name="sales_schema", include_columns=True)
   • 特定のテーブルに関心がある場合は、次のようにします： describe_uc_table(full_table_name="prod_catalog.sales_schema.orders")
5. データのリネージを分析し、処理コードを特定する：describe_uc_table(full_table_name="prod_catalog.sales_schema.orders", include_lineage=True)
   • エージェントは、上流のテーブル、下流の依存関係、およびこのデータを処理するノートブックを特定します。
   • たとえば、/Repos/production/etl/sales_processing.py がこのテーブルに書き込んでいることを確認します。
6. データ変換ロジックを調べる：エージェントが IDE／リポジトリ内でノートブックファイル /Repos/production/etl/sales_processing.py を直接読み取ります。
   • エージェントは実際の Python／SQL コードを分析し、ビジネスルール、データ品質チェック、変換ロジックを理解します。
7. クエリを作成して実行する：execute_sql_query(sql="SELECT customer_id, order_date, SUM(order_total) FROM prod_catalog.sales_schema.orders WHERE order_date > '2023-01-01' GROUP BY customer_id, order_date ORDER BY order_date DESC LIMIT 100")

Terraform でメタデータをコードとして管理する

Databricks の UI からメタデータを手動で入力する方法もありますが、Unity Catalog のメタデータをコードとして定義する方が、より堅牢で拡張性に優れた方法です。Terraform などのツールを使うと、カタログやスキーマを含むデータガバナンスオブジェクトを宣言的に管理できます。これには次のような利点があります。

• バージョン管理：メタデータの定義を Git に保存し、他のインフラストラクチャコードとともに追跡およびバージョン管理できます。
• 再現性と一貫性：環境（dev、staging、prod）間でメタデータの一貫性を保てます。
• 自動化：メタデータ管理を CI/CD パイプラインに統合できます。
• 中核となるアセットの保守が容易：動的な性質のため、新しいテーブルをすべてコードとして定義するのは複雑ですが、カタログやスキーマなどの中核となるアセットは比較的安定しているため、この方法のメリットを大きく得られます。定義やコメントをコードとして管理することで、データ環境の永続的で十分に文書化された基盤を確保できます。

Databricks Provider for Terraform を使って、カタログとそのスキーマを定義する方法の例を示します。

resource "databricks_catalog" "prod_catalog" {
  name          = "prod"
  comment       = "Main production catalog for all enterprise data."
  storage_root  = var.default_catalog_storage_root
  force_destroy = false
}

# Schemas within the 'prod' catalog
resource "databricks_schema" "prod_raw" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "raw"
  comment      = "Raw data for all different projects, telemetry, game data etc., before any transformations. No schema enforcement."
}

resource "databricks_schema" "prod_bi_conformed" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "bi_conformed"
  comment      = "Conformed (silver) schema for Business Intelligence, cleaned and well-formatted. Schema enforced."
}

resource "databricks_schema" "prod_bi_modeled" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "bi_modeled"
  comment      = "Modeled (gold) schema for Business Intelligence, aggregated and ready for consumption. Schema enforced."
}

Unity Catalog に既存のカタログやスキーマがあっても心配はいりません。メタデータをコードとして管理するために、それらを再作成する必要はありません。Terraform の terraform import コマンドを使うと、Unity Catalog のアセットを含む既存のインフラストラクチャを Terraform の管理対象に取り込めます。インポート後は、Terraform の設定にリソースを定義し、アセット自体には影響を与えずに comment フィールドなどの属性だけを選択的に更新できます。たとえば、既存のスキーマをインポートした後、.tf ファイルで comment を追加または更新すると、terraform apply はその変更のみを適用します。

特にカタログやスキーマなどの基盤となる要素に対してメタデータをコードとして管理する戦略を採用すると、この MCP サーバーが利用するメタデータの品質と信頼性が大幅に向上します。その結果、Databricks のデータを扱う AI エージェントの有効性もさらに高まります。

Databricks Unity Catalog で Terraform を使用する方法の詳細については、公式ドキュメントを参照してください。

• Databricks Provider：Catalog リソース (https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/catalog)
• Databricks Provider：Schemas データソース (https://registry.terraform.io/providers/databricks/databricks/latest/docs/data-sources/schemas)

長時間実行されるクエリの処理

execute_sql_query ツールは、Databricks SDK の execute_statement メソッドを使用します。内部で使用される databricks_sdk_utils.execute_databricks_sql 関数の wait_timeout パラメーターは '50s' に設定されています。クエリの実行時間がこれを超えると、SDK はポーリング用のステートメント ID を返す場合がありますが、現在のツール実装は同期処理に近い応答を得るため、この時間まで待機します。非常に時間のかかるクエリでは、このタイムアウトに達する可能性があります。

依存関係

• databricks-sdk：Databricks REST API および Unity Catalog との連携に使用します。
• python-dotenv：.env ファイルから環境変数を読み込むために使用します。
• mcp[cli]：Model Context Protocol ライブラリです。
• asyncio：MCP サーバー内での非同期処理に使用します。
• httpx（通常は databricks-sdk または mcp のサブ依存関係）：HTTP リクエストの送信に使用します。