looker-mcp-skill

Looker MCP サーバーのスキル

このスキルでは、Looker Model Context Protocol（MCP）サーバーへのアクセス方法、設定方法、使用方法について説明します。AI アシスタント、ローカル IDE（VS Code、Cursor、Claude Desktop、Gemini CLI）、自動エージェントが Looker インスタンスと直接連携し、データのクエリ、セマンティックモデルの確認、LookML プロジェクトの管理、システム診断の実行を行えるようにします。

---

1. Looker MCP サーバーへのアクセス

Looker では、MCP サーバーに対して主に 2 種類のデプロイ方法がサポートされています。

A. Looker 管理の MCP サーバー（Cloud／GCP Core に推奨）

Looker 管理の MCP サーバーは、Looker インスタンス（Looker Core および Looker Original）に直接組み込まれています。Google Cloud がホストおよび管理するため、別途サーバーインフラストラクチャを実行する必要はありません。

• エンドポイント：https://<YOUR_LOOKER_INSTANCE_URL>/mcp
• 有効化：
  1. Admin Panel > Platform > MCP に移動します。
  2. Enable MCP Server を On に切り替えます。
  3. ユーザーとクライアントアプリケーションに適切な API 権限と機能権限があることを確認します。

B. ローカル／スタンドアロン MCP サーバー（MCP Toolbox for Databases）

顧客ホスト型（オンプレミス）インスタンス、カスタム開発環境、スタンドアロン CLI 統合では、MCP Toolbox for Databases（@google/mcp-toolbox）を使用して MCP サーバーをローカルで実行できます。

• インストール／起動：

  npx @google/mcp-toolbox --prebuilt=looker,looker-dev
  

  または Docker を使用する場合：

  docker run -p 5000:5000 \
    -e LOOKER_BASE_URL="https://your-instance.looker.com" \
    -e LOOKER_CLIENT_ID="<CLIENT_ID>" \
    -e LOOKER_CLIENT_SECRET="<CLIENT_SECRET>" \
    us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt=looker,looker-dev --address=0.0.0.0
  

• 環境変数：

  • LOOKER_BASE_URL：Looker インスタンスのベース URL（例：https://mycompany.looker.com）。
  • LOOKER_CLIENT_ID：Looker API 4.0 のクライアント ID。
  • LOOKER_CLIENT_SECRET：Looker API 4.0 のクライアントシークレット。
  • LOOKER_VERIFY_SSL：自己署名の開発用証明書を使用する場合は false に設定します（デフォルト：true）。

• Cloud Run へのデプロイ： Google Cloud Run で MCP Toolbox サーバーを実行する方法については、Looker Cloud Run サンプルを参照してください。

---

2. OAuth 認証の設定

AI アプリケーションやクライアントがユーザーに代わって安全に認証できるようにするには、Looker でクライアントアプリケーションを OAuth クライアントとして登録します。

ステップ 1：OAuth クライアントアプリケーションの登録

API Explorer 拡張機能（推奨）または curl を使用して、OAuth クライアントアプリケーションを登録できます。

オプション A：Looker API Explorer を使用する（推奨）

API Explorer 拡張機能は、Looker のインストールにデフォルトで含まれています。

1. Looker を開き、Applications > API Explorer に移動します（または https://<YOUR_LOOKER_INSTANCE_URL>/extensions/marketplace_extension_api_explorer::api-explorer/ にアクセスします）。
2. register_oauth_client_app エンドポイント（POST /oauth_client_apps/{client_guid}）を検索します。
3. <CLIENT_GUID> を入力し、リクエスト本文のパラメーター（client_guid、display_name、redirect_uri、enabled: true）を設定します。
4. Run Request を実行して、アプリケーションを登録します。

オプション B：curl を使用する

または、Looker の oauth_client_apps エンドポイントに HTTP POST リクエストを送信します。

curl -X POST "https://<YOUR_LOOKER_INSTANCE_URL>/api/4.0/oauth_client_apps/<CLIENT_GUID>" \
  -H "Authorization: Bearer <ADMIN_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_guid": "<CLIENT_GUID>",
    "display_name": "My AI Assistant Client",
    "redirect_uri": "http://127.0.0.1:7777/oauth/callback",
    "enabled": true
  }'

• <CLIENT_GUID>：インテグレーション用に生成された一意のクライアント識別子です。注：クライアントアプリケーションの設定（例：IDE または AI クライアントの OAuth 設定）で、OAuth Client ID（clientId）にこの <CLIENT_GUID> を設定してください。
• redirect_uri：認可コードの送信先となるコールバック URL です。注：redirect_uri は、登録するクライアントまたは IDE アプリケーションによって異なります。
  • Antigravity：https://antigravity.google/oauth-callback
  • Claude Desktop / Claude AI：https://claude.ai/api/mcp/oauth/callback または http://localhost:<PORT>/oauth/callback
  • VS Code / Cloud Code Extension：https://vscode.dev/redirect または http://127.0.0.1:<PORT>/oauth/callback
  • Cursor Desktop：https://cursor.com/mcp/callback
  • 汎用 CLI / ローカルツール：http://127.0.0.1:7777/oauth/callback または http://localhost:8080/callback

設定例：クライアントの OAuth 認証情報とクライアント GUID の設定手順については、Looker OAuth を使用した Claude Desktop の設定を参照してください。

手順 2：OAuth PKCE フロー／ベアラー認証を実行する

1. ユーザーを認可 URL にリダイレクトする： PKCE コード検証子と SHA-256 チャレンジを生成し、ユーザーを次の URL にリダイレクトします。

   https://<YOUR_LOOKER_INSTANCE_URL>/auth/oauth?client_id=<CLIENT_GUID>&response_type=code&code_challenge=<PKCE_CHALLENGE>&code_challenge_method=S256&redirect_uri=<REDIRECT_URI>
   

2. 認可コードをアクセストークンとリフレッシュトークンに交換する： PKCE ハンドシェイクを完了するため、code_verifier を含めてトークンエンドポイントに POST リクエストを送信します。

   curl -X POST "https://<YOUR_LOOKER_INSTANCE_URL>/api/4.0/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "client_id=<CLIENT_GUID>" \
     -d "redirect_uri=<REDIRECT_URI>" \
     -d "code=<AUTHORIZATION_CODE>" \
     -d "code_verifier=<CODE_VERIFIER>"
   

3. MCP リクエストを認証する： MCP サーバーに送信するリクエストの HTTP ヘッダーに、取得した access_token を含めます。

   Authorization: Bearer <ACCESS_TOKEN>
   

---

3. MCP クライアントの接続（IDE／エージェントの設定）

サーバーのエントリをクライアント設定ファイル（例：.mcp.json、Cursor mcp.json、または Gemini CLI の設定ファイル）に追加します。

リモート／管理対象 MCP の設定

ネイティブ OAuth クライアント（例：Claude Desktop）

OAuth フローをネイティブでサポートするクライアントは、サーバー URL を設定すると認可を自動的に処理します。

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "https://<YOUR_LOOKER_INSTANCE_URL>/mcp"
    }
  }
}

注：ネイティブ OAuth クライアントでは、登録済みの <CLIENT_GUID> を Client ID として使用して、クライアントの OAuth 設定を行ってください。詳細については、Claude Desktop の設定を参照してください。

標準 HTTP クライアント／カスタムスクリプト（ヘッダー経由のベアラートークン）

OAuth ログインフローをネイティブで開始しない標準 HTTP MCP クライアントまたはカスタムスクリプトでは、事前に取得した認証トークンを headers フィールドに渡します。

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "https://<YOUR_LOOKER_INSTANCE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

ローカル／スタンドアロン MCP の設定

Stdio モード（npx 経由）

{
  "mcpServers": {
    "Looker": {
      "command": "npx",
      "args": ["-y", "@google/mcp-toolbox", "--prebuilt=looker,looker-dev"],
      "env": {
        "LOOKER_BASE_URL": "https://<YOUR_LOOKER_INSTANCE_URL>",
        "LOOKER_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "LOOKER_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>"
      }
    }
  }
}

HTTP モード（Docker コンテナ経由）

セクション 1.B に記載されているように、Docker 経由でスタンドアロン MCP サーバーを実行している場合は、MCP URL に http://localhost:5000/mcp を指定して MCP クライアントを接続します。

{
  "mcpServers": {
    "Looker": {
      "httpUrl": "http://localhost:5000/mcp"
    }
  }
}

---

4. MCP で利用できるツール

Looker MCP Server は、6 つの機能領域に分類された45 個のツールを公開しています。

📊 データとクエリの実行

ツール	説明
query	LookML モデル、Explore、ディメンション、メジャー、フィルター、並べ替え、上限を使用して構造化クエリを実行します。
query_sql	指定されたクエリ定義に対し、Looker がコンパイルした基盤となる SQL クエリを生成します。
query_url	Looker の共有可能なクエリ URL またはスラッグを指定して、クエリを実行するか解決します。
run_look	ID で保存済み Look を実行し、データセットの結果を返します。
run_dashboard	指定された Dashboard ID の要素クエリを実行します。

🔍 検出とメタデータカタログ

ツール	説明
get_models	インスタンスで利用可能なすべての LookML モデルを一覧表示します。
get_explores	LookML モデル内で定義されている Explore を一覧表示します。
get_dimensions	Explore に定義されているディメンションフィールドを取得します。
get_measures	Explore に定義されているメジャーフィールドを取得します。
get_filters	Explore に定義されているフィルター専用フィールドを取得します。
get_parameters	Explore に定義されているパラメーターを取得します。
get_connections	データベース接続の設定を一覧表示します。
get_connection_databases	接続経由でアクセスできるデータベースを一覧表示します。
get_connection_schemas	データベース接続内のスキーマを一覧表示します。
get_connection_tables	接続スキーマ内のデータベーステーブルを一覧表示します。
get_connection_table_columns	データベーステーブルの列とメタデータを一覧表示します。

🎨 ダッシュボードとコンテンツの作成

ツール	説明
get_looks	保存済みの Look を検索して取得します。
get_dashboards	ユーザー定義のダッシュボードと LookML ダッシュボードを検索して取得します。
make_look	クエリ定義から新しい Look を作成します。
make_dashboard	新しいダッシュボードコンテナを作成します。
add_dashboard_element	ダッシュボードに可視化要素／データ要素を追加します。
add_dashboard_filter	ダッシュボードに動的なインタラクティブフィルターを追加します。
generate_embed_url	Looker コンテンツの埋め込みに使用する、署名付き SSO 埋め込み URL を生成します。

🛠️ LookML プロジェクトの開発

ツール	説明
dev_mode	API セッションの開発モードと本番モードを切り替えます。
get_projects	セッションからアクセスできるすべての LookML プロジェクトを一覧表示します。
get_project_directories	プロジェクトのディレクトリ構造ツリーを取得します。
get_project_files	LookML プロジェクト内のファイルを一覧表示します。
get_project_file	指定した LookML ファイルの行の内容を表示します。
create_project_file	新しい LookML ファイル（.lkml、.md など）を作成します。
update_project_file	既存の LookML ファイルの行の内容を更新します。
delete_project_file	プロジェクトのワークスペースから LookML ファイルを削除します。
create_project_directory	LookML プロジェクト内にサブディレクトリを作成します。
delete_project_directory	プロジェクトのサブディレクトリを削除します。
create_view_from_table	データベーステーブルから標準的な LookML ビュー定義を自動生成します。
validate_project	LookML バリデーターを実行し、コンパイルエラー／警告を返します。
get_lookml_tests	LookML で記述されたデータテストの定義を取得します。
run_lookml_tests	LookML データテストを実行し、合格／不合格のステータスを返します。

🌿 Git バージョン管理

ツール	説明
get_git_branch	LookML プロジェクトのアクティブな Git ブランチの状態を取得します。
list_git_branches	リモートおよびローカルの Git ブランチを一覧表示します。
create_git_branch	新しい Git 作業ブランチを作成します。
switch_git_branch	プロジェクトセッションのコンテキストを指定した Git ブランチに切り替えます。
delete_git_branch	指定した Git ブランチを削除します。

⚙️ 開発者向けユーティリティと診断ツール

ツール	説明
health_pulse	Looker インスタンスの軽量な稼働状況およびヘルスチェックを実行します。
health_analyze	インスタンスのクエリパフォーマンスを監査し、遅いクエリや PDT のボトルネックを特定します。
health_vacuum	利用されていないコンテンツ、未使用の Explore、クリーンアップ候補のオブジェクトを特定します。

---

5. セキュリティと認可に関するガイドライン

1. ユーザースコープの適用と OAuth コンテキスト：ユーザーレベルのスコープ適用とアクセス制御（アクセス許可、モデルセット、ユーザーロールなど）は、Looker-Managed MCP Server（OAuth を介してユーザーを認証）を使用する場合、またはスタンドアロンサーバーにユーザー固有の OAuth トークンを設定する場合に適用されます。
2. 静的 API 認証情報に関する警告：スタンドアロン／ローカル MCP サーバーを静的な環境変数の認証情報（LOOKER_CLIENT_ID および LOOKER_CLIENT_SECRET。共有 Cloud Run サービスとしてのデプロイなど）でデプロイすると、すべてのツールの実行が、その単一の API 認証情報ペアのセキュリティコンテキストで行われます。これにより、個々のユーザーレベルのアクセス制御や行レベルのセキュリティルールが迂回される可能性があります。
3. 開発モードの分離：プロジェクトファイルを編集するときは、ステージングしてコミットする前に、必ず dev_mode を true に切り替えて、個人用の開発者ワークスペースブランチに編集内容を分離してください。

---

6. 代替ツール：Looker CLI（looker-cli）

ターミナルでのワークフロー、シェルスクリプト、CI/CD パイプライン向けに、Looker API の操作に使用できるコマンドラインの代替手段として、**Looker CLI（looker-cli）**を利用できます。

• リポジトリ：Looker CLI の GitHub リポジトリ
• ユースケース：シェルスクリプト、ターミナルでの対話型コマンド、CI/CD の自動化、開発者のオンボーディングワークフロー（installing-looker-cli および authenticating-looker-cli のスキルを参照）。