Claude Media
dbt Semantic Layerの使い方 — Claudeでメトリクスに自然言語で問い合わせる
Claude CodeMCPClaude連携チュートリアル

dbt Semantic Layerの使い方 — Claudeでメトリクスに自然言語で問い合わせる

dbt MCPサーバー経由でdbt Semantic Layerに接続し、Claudeから自然言語でメトリクスを問い合わせる手順と7つの専用ツールをまとめます。

読了目安 約13分

MCPはAIエージェントと外部ツールをつなぐ標準プロトコルで、仕組み自体はMCPとはにまとめています。dbt Semantic Layerは、revenueのような業務指標(メトリクス)の定義をBIツールごとにバラバラに書く代わり、dbtのモデル層に一元化する仕組みです。dbt MCPサーバーにはこのSemantic Layerを操作する7つの専用ツールが含まれています。Claudeに接続すれば、SQLを書かずに「先月の地域別売上を見せて」のような自然文でメトリクスを問い合わせられます。

dbtのモデルをbuild・compile・runで実行したりリネージを追ったりする使い方はdbt MCPサーバーの使い方で扱っています。この記事はSemantic Layer側のツールと、つながらないときの切り分けに絞ります。

接続の前に必要な3つの条件

dbt Semantic LayerはMetricFlowが動作の中核で、メトリクスの定義をBIレイヤーではなくdbtプロジェクト側に置きます。ある指標の定義が変われば、それを参照しているダッシュボードやレポートすべてに反映されます。部署ごとに微妙に違う「売上」が並ぶ事態を避けられる設計です。

Claudeから問い合わせる前に、次の3つが揃っている必要があります。

前提

Semantic Layerに問い合わせるまでの準備

  1. 1

    dbt platformのStarterまたはEnterprise-tierアカウント

    メトリクスの定義と照会はdbt platformのStarter・Enterprise・Enterprise+が対象です。dbt Core単体では、Semantic Layerのメトリクス定義も、APIやMCPを通した外部からの問い合わせも使えません。

  2. 2

    メトリクスを定義して本番環境にデプロイ

    semantic_modelsとmetricsをコミット・マージし、デプロイ環境(Orchestration → Environments)でdeployジョブを走らせます。ジョブにはdbt parseを含め、dbt v2を使っている場合はdbt docs generateも加えます。ジョブが成功すると、Semantic Layer APIが最新のマニフェストを読めるようになります。

  3. 3

    サービストークンかPAT、本番環境ID

    トークンには少なくともSemantic Layer・Metadata・Developerの権限が要ります。Semantic Layerで使うならPATが推奨です。本番環境IDは数値で、ブラウザのURLそのものではありません。

使える7つのツール

dbt MCPサーバーのSemantic Layerカテゴリーには次の7ツールがあります。

ツールできること
list_metricsできること定義済みのメトリクスを全件取得する
get_dimensionsできること指定したメトリクスに紐づくディメンション(切り口)を取得する
get_dimension_valuesできることあるディメンションが取りうる値を取得する。メトリクスを指定して絞り込み可能
get_entitiesできること指定したメトリクスに紐づくエンティティを取得する
get_metrics_compiled_sqlできることメトリクスをクエリせず、コンパイル後のSQLだけを返す
query_metricsできることフィルタとグルーピングを指定してメトリクスを実際にクエリする
list_saved_queriesできること保存済みクエリを一覧表示する

query_metricsが実際にデータを引く中心のツールで、残りはメトリクスの構造を把握するための補助です。メトリクス数が10件以下なら、list_metricsの応答にディメンションとエンティティの名前が最初から埋め込まれます(DBT_MCP_SL_METRICS_RELATED_MAXの既定値が10)。この場合はget_dimensionsを別途呼ばずに済みます。

10件を超えると、list_metricsはメトリクス名だけを返します。Claudeが名前を見てから、必要な分だけget_dimensions・get_entitiesを呼ぶ2段階の動きに変わります。

保存済みクエリ(saved queries)は、関連するメトリクス・ディメンション・フィルタをまとめて名前を付けたもので、dbtのDAG上にノードとして現れます。list_saved_queriesで一覧を引けば、定義済みのメトリクス・ディメンション・フィルタの組み合わせを確認できます。

Claudeへの接続方法 — self-hostedとremote

Semantic Layerツールは、self-hosted構成とremote構成のどちらでも使えます。選ぶ軸は、手元のdbtプロジェクトも同じ接続で操作したいかどうかです。

項目self-hostedremote(OAuth)remote(トークン)
インストールself-hosteduvが必要remote(OAuth)不要remote(トークン)Claude Codeは不要。Claude Desktopはnpx(Node.js)が必要
認証self-hostedDBT_TOKENを発行(OAuthも可)remote(OAuth)ブラウザでOAuth同意remote(トークン)PATまたはサービストークンをヘッダーで渡す
主な用途self-hostedCLIも同時に使いたい開発者remote(OAuth)ワンクリックで始めたい利用者remote(トークン)CIやトークン共有が必要な環境

self-hostedで接続する

Semantic Layerも使う場合、claude mcp addにDBT_HOST・DBT_TOKEN・DBT_PROD_ENV_IDの3つを渡します。

claude mcp add dbt \
  -e DBT_HOST=abc123.us1.dbt.com \
  -e DBT_TOKEN=your-token-here \
  -e DBT_PROD_ENV_ID=12345 \
  -- uvx dbt-mcp

DBT_HOSTはdbt platformのアカウント情報にあるAccess URLのホスト名で、サブドメインまで含めて書きます。DBT_PROD_ENV_IDは数値の環境IDです。

PATをDBT_TOKENに使う場合は、DBT_ACCOUNT_ID(数値のアカウントID)も必要です。CLIコマンドを使わずSemantic Layerだけに絞りたいなら、DBT_PROJECT_DIRとDBT_PATHを渡さなければ構いません。CLIツールは自動的に無効化され、dbt platform系のツールだけが残ります。

必須の変数が足りないときも、エラーにはならず、そのツールセットが黙って無効になります。Semantic Layerのツールが並ばないときは、DBT_MCP_LOG_LEVEL=DEBUGを付けて起動し、サーバーログでどのツールセットが有効かを見ると原因を絞れます。

remoteでOAuth接続する

Claude Codeからremote MCPサーバーに直接つなぐ場合は、.mcp.jsonに次のように書くか、CLIで登録します。

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

初回接続時にブラウザが開き、dbt platformへのサインインとスコープの同意を求められます。スコープは自分の既存の権限を絞り込むフィルターで、新しい権限を足すものではありません。プロジェクトも全件か一部かを選べます。

OAuthにはもう1つ条件があります。静的なサブドメイン(abc123.us1.dbt.comのabc123)を持つアカウントだけが対象で、サブドメインがないアカウントはサポートへの問い合わせが必要です。remote MCP OAuthはStarter・Enterprise・Enterprise+アカウントの公開ベータです。

remoteでトークン接続する

OAuthに対応していないクライアントや、CI・共有環境では、ヘッダーでトークンを渡します。

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
        "x-dbt-prod-environment-id": "12345"
      }
    }
  }
}

AuthorizationはTokenでもBearerでも書けます。x-dbt-dev-environment-idとx-dbt-user-idはexecute_sqlやdbt v2のツールを使うときに足すヘッダーで、Semantic Layerの照会だけなら要りません。Claude Desktopは"type": "http"をJSON設定で受け付けないため、mcp-remoteプロキシをnpxで起動する書き方になり、Node.jsが必要です。

execute_sqlはself-hostedでは既定で無効です(DISABLE_SQLの既定がtrue)。使いたいときはDISABLE_SQL=falseを渡します。

自然言語でメトリクスに問い合わせる実例

接続が終われば、あとは自然文で聞くだけです。

定義済みのメトリクスを一覧で見せて

list_metricsが呼ばれ、メトリクス数が少なければディメンションとエンティティの名前も一緒に返ってきます。特定の指標を掘り下げたいときは、フィルタとグルーピングを含めて聞きます。

先月のrevenueを地域別・プラン別に見せて

この聞き方ではquery_metricsがrevenueメトリクスにregionとplanのディメンションを指定して呼ばれ、集計済みの結果が返ります。実行前にSQLだけ確認したい場合は、聞き方を変えます。

revenueメトリクスをregion別に集計するSQLだけ見せて(実行はしないで)

get_metrics_compiled_sqlはメトリクスをクエリせずコンパイル後のSQLだけを返すため、ウェアハウスに余計な実行コストをかけずに定義の妥当性を確認できます。

ディメンションにどんな値が入っているか分からないまま絞り込みたいときは、値の候補を先に確認します。

revenueメトリクスのregionディメンションには、どんな値が入ってる?

get_dimension_valuesがメトリクスを指定した状態で呼ばれ、そのメトリクスの計算に使われているregionの値だけが返ります。japanかJPかといった表記ゆれも、値の一覧を見てから条件を組み立てられます。

つながらない・空で返るときの切り分け

症状ごとに、見る場所を分けます。

症状見る場所
list_metricsが空を返す見る場所アカウントがStarter/Enterprise-tierか。semantic_modelsとmetricsを定義し、本番環境でdeployジョブを成功させたか
接続自体が失敗する見る場所DBT_PROD_ENV_IDなどに数値でなくURLを貼っていないか。remoteのURLでhttps://が二重になっていないか
Semantic Layerのツールだけ並ばない見る場所DBT_HOSTの未設定でツールセットが黙って無効になっていないか(DBT_MCP_LOG_LEVEL=DEBUGで確認)
execute_sqlが動かない見る場所サービストークンを使っていないか。self-hostedならDISABLE_SQL=falseか
ツールの一部だけ消えている見る場所DISABLE_SEMANTIC_LAYERやDISABLE_TOOLS、remoteならx-dbt-disable-toolsetsヘッダーで切っていないか
Claude Desktopでspawn uvx ENOENTやspawn npx ENOENT見る場所which uvx・which npxで出たフルパスをcommandに書く

list_metricsのCSV応答は、メトリクス数がDBT_MCP_SL_METRICS_RELATED_MAXを超え、かつ応答がDBT_MCP_SL_MAX_RESPONSE_CHARS(既定16,000文字)を超えたときに、descriptionとmetadataの列を省略します。メトリクスが多いプロジェクトで説明文が返ってこないのはこの挙動のためで、全文が必要なら変数を大きくするか0にして省略を止めます。

DBT_MCP_ENABLE_*=のように空の値で書いた行があると、許可リスト方式に切り替わり、ほかのツールセットがすべて無効になります。空の行は残さず、使うツールセットだけ値を入れて書きます。

制限事項

制約は2つあります。1つはレート制限です。remote MCPはdbt platformの他のAPIと同じグローバルレート制限を共有します。上限は1IPあたり毎分5,000リクエストです。self-hostedはDiscovery APIやAdmin APIの公開レート制限に従います。

もう1つはデータ保持です。dbt MCPサーバー自体は本番データやジョブ実行結果を保持しない読み取り専用のアクセス層で、ツール呼び出しのたびにdbt platformからリアルタイムで読み出します。ジョブの実行結果がどれだけ残るかは、dbt platform側のデータ保持ポリシーが決めます。

remote MCPは、build・run・testのようなdbt CLIコマンドとローカルのプロジェクトアクセスに対応していません。Codegenツールもself-hosted向けです。

BIダッシュボードとの役割分担

Semantic Layerのメトリクス定義はBIツールの機能を代替するものではなく、BIツールが参照する定義元を一本化するものです。Tableau、Power BI、Google Sheets、Excelなど複数の下流ツールと統合でき、どのツールから見ても数値は同じdbtの定義に基づきます。

Claudeからの自然言語問い合わせは、ダッシュボードを新しく作るまでもない一回限りの確認や、ディメンションを変えながら試す探索的な分析に向いています。定期配信するレポートや複数人が繰り返し参照するダッシュボードはBIツール側に残し、裏側の定義だけをSemantic Layerに寄せる分担が実態に近い形です。

ウェアハウスに直接クエリを投げたいなら、Claude Snowflake連携のようなDB専用のMCPサーバーという選択肢もあります。Semantic Layerがメトリクス定義を経由するのに対し、こちらは生のテーブルへの自由なSQL探索に向きます。

まとめ

つながらないときは、ツールの設定より先に、アカウントの種類・deployジョブの成功・トークンの種類を順に見ます。Claude Codeで始めるなら、OAuthが使えるアカウントはremote、手元のdbtプロジェクトも触りたい場合はself-hostedを選ぶ形になります。

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

関連する記事

Claude Code をもっと見る →