Lightdash Mcp

Lightdash MCP サーバー

Model Context Protocol（MCP）を使用して、Claude、Cursor、その他の AI アシスタントを Lightdash の分析機能に接続します。

Lightdash と連携する Model Context Protocol（MCP）サーバーです。LLM がプログラムからデータを探索し、チャートを作成し、ダッシュボードを管理できるようにします。

機能

この MCP サーバーは、データ分析のワークフロー全体を支援する包括的なツールセットを提供します。

• 探索：データカタログを確認し、テーブルや探索対象を見つけ、スキーマを把握します
• クエリ：フィルター、メトリクス、集計を全面的にサポートしてクエリを実行します
• チャート管理：複雑な可視化を含むチャートの作成、読み取り、更新、削除を行います
• ダッシュボード管理：タイル、フィルター、レイアウトを含むダッシュボードを作成、管理します
• リソースの整理：コンテンツを整理するスペースを作成、管理します

インストール

前提条件

• Python 3.10+
• Lightdash インスタンス（クラウドまたはセルフホスト）
• Lightdash パーソナルアクセストークン（Lightdash のプロフィール設定から取得）

pip でクイックスタート（推奨）

pip install lightdash-mcp

uvx でクイックスタート

uvx lightdash-mcp

pipx でクイックスタート

pipx run lightdash-mcp

ソースからインストール

git clone https://github.com/poddubnyoleg/lightdash_mcp.git
cd lightdash_mcp
pip install .

Google Cloud IAP のサポート

Lightdash インスタンスが Google Cloud Identity-Aware Proxy の背後にある場合（例：--iap を使用する Cloud Run）、iap エクストラを指定してインストールします。

pip install lightdash-mcp[iap]
# or from source
pip install .[iap]

IAP_ENABLED=true を設定します。サーバーは IAM Credentials API を介して JWT（オーディエンス {LIGHTDASH_URL}/*）に署名し、すべてのリクエストに Proxy-Authorization: Bearer <jwt> として付加します。Lightdash 用の Authorization: ApiKey ヘッダーは維持されます。

サービスアカウント認証情報とユーザー認証情報（Application Default Credentials / ADC）の両方がサポートされています。

サービスアカウント認証情報（Cloud Run、GCE などでのデフォルト）：

• ランタイムのサービスアカウントには、自身に対する roles/iam.serviceAccountTokenCreator が必要です
• ランタイムのサービスアカウントには、Cloud Run サービスに対する roles/iap.httpsResourceAccessor が必要です

ユーザー認証情報（ADC）（例：gcloud auth application-default login）：

• JWT への署名時に偽装するサービスアカウントのメールアドレスを IAP_SA に設定します
• ユーザーには、対象のサービスアカウントに対する roles/iam.serviceAccountTokenCreator が必要です
• 対象のサービスアカウントには、Cloud Run サービスに対する roles/iap.httpsResourceAccessor が必要です

設定

環境変数

サーバーには次の環境変数が必要です。

変数	必須	説明	例
LIGHTDASH_TOKEN	✅	Lightdash パーソナルアクセストークン	ldt_abc123...
LIGHTDASH_URL	✅	Lightdash インスタンスのベース URL	https://app.lightdash.cloud
CF_ACCESS_CLIENT_ID	❌	Cloudflare Access クライアント ID（CF Access の背後にある場合）	-
CF_ACCESS_CLIENT_SECRET	❌	Cloudflare Access クライアントシークレット（CF Access の背後にある場合）	-
LIGHTDASH_PROJECT_UUID	❌	デフォルトのプロジェクト UUID（未設定の場合、最初に利用可能なプロジェクトを使用）	3fc2835f-...
IAP_ENABLED	❌	Google Cloud IAP 認証を有効化します（true/1）	true
IAP_SA	❌	ユーザー認証情報（ADC）使用時の IAP 用サービスアカウントのメールアドレス	[email protected]

Lightdash トークンの取得方法

1. Lightdash インスタンスにログインします
2. 設定 → パーソナルアクセストークンに移動します
3. 新しいトークンを生成をクリックします
4. トークン（ldt_ で始まるもの）をコピーします

Claude Desktop での使用

以下を claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "lightdash": {
      "command": "uvx",
      "args": ["lightdash-mcp"],
      "env": {
        "LIGHTDASH_TOKEN": "ldt_your_token_here",
        "LIGHTDASH_URL": "https://app.lightdash.cloud",
        "LIGHTDASH_PROJECT_UUID": "your-project-uuid"
      }
    }
  }
}

Claude Code（CLI）での使用

プロジェクトのルートに .mcp.json を作成するか、編集します。

{
  "mcpServers": {
    "lightdash": {
      "type": "stdio",
      "command": "lightdash-mcp",
      "env": {
        "LIGHTDASH_URL": "https://your-lightdash-instance.com",
        "LIGHTDASH_TOKEN": "ldt_your_token_here",
        "LIGHTDASH_PROJECT_UUID": "your-project-uuid"
      }
    }
  }
}

Claude Code を再起動し、/mcp を実行してサーバーが接続済みと表示されることを確認します。

注：.mcp.json にシークレットが含まれている場合は、コミットしないでください。.gitignore に追加します。

その他の MCP クライアントでの使用

実行前に環境変数をエクスポートします。

export LIGHTDASH_TOKEN="ldt_your_token_here"
export LIGHTDASH_URL="https://app.lightdash.cloud"
lightdash-mcp

利用可能なツール

📊 検出とメタデータ

ツール	説明
list-projects	利用可能な Lightdash プロジェクトをすべて一覧表示します
get-project	特定のプロジェクトの詳細情報を取得します
list-explores	プロジェクト内で利用可能な Explore／テーブルをすべて一覧表示します
get-explore-schema	特定の Explore の詳細なスキーマ（ディメンション、メトリクス、結合）を取得します
list-spaces	プロジェクト内のすべてのスペース（フォルダー）を一覧表示します
get-custom-metrics	プロジェクトで定義されたカスタムメトリクスを取得します

📈 チャート管理

ツール	説明
list-charts	保存済みチャートをすべて一覧表示します。名前で絞り込むこともできます
search-charts	名前または説明でチャートを検索します
get-chart-details	特定のチャートの完全な設定を取得します
create-chart	メトリクスクエリと可視化設定を指定して、新しい保存済みチャートを作成します
update-chart	既存のチャートの設定（名前、説明、クエリ、可視化）を更新します
run-chart-query	チャートのクエリを実行し、データを取得します
delete-chart	保存済みチャートを削除します

📋 ダッシュボード管理

ツール	説明
list-dashboards	プロジェクト内のすべてのダッシュボードを一覧表示します
create-dashboard	新しいダッシュボードを作成します（空の状態、またはタイル付き）
duplicate-dashboard	既存のダッシュボードを新しい名前で複製します
get-dashboard-tiles	ダッシュボードのすべてのタイルを取得します。完全な設定を含めることもできます
get-dashboard-tile-chart-config	特定のダッシュボードタイルの完全なチャート設定を取得します
get-dashboard-code	ダッシュボードの完全な設定をコードとして取得します
create-dashboard-tile	新しいタイル（チャート、Markdown、または loom）をダッシュボードに追加します
update-dashboard-tile	タイルのプロパティ（位置、サイズ、内容）を更新します
rename-dashboard-tile	ダッシュボードのタイル名を変更します
delete-dashboard-tile	ダッシュボードからタイルを削除します
update-dashboard-filters	ダッシュボードレベルのフィルターを更新します
run-dashboard-tiles	ダッシュボード上の1つ、複数、またはすべてのタイルを同時に実行します

🔍 クエリ実行

ツール	説明
run-chart-query	保存済みチャートのクエリを実行し、データを返します
run-dashboard-tiles	ダッシュボードのタイルのクエリを実行します（一括実行に対応）
run-raw-query	任意の Explore に対してアドホックなメトリクスクエリを実行します

🗂️ リソース管理

ツール	説明
create-space	チャートやダッシュボードを整理するための新しいスペースを作成します
delete-space	空のスペースを削除します

プロジェクト構成

.
├── pyproject.toml              # Package configuration
├── lightdash_mcp/              # Main package
│   ├── __init__.py             # Package init
│   ├── server.py               # MCP server entry point
│   ├── lightdash_client.py     # Lightdash API client
│   └── tools/                  # Tool implementations
│       ├── __init__.py         # Auto-discovery and tool registry
│       ├── base_tool.py        # Base tool interface
│       └── *.py                # Individual tool implementations
├── README.md
└── LICENSE

開発

新しいツールの追加

サーバーは tools/ ディレクトリからツールを自動検出して登録します。新しいツールを追加するには、次の手順に従います。

1. 新しいファイルを作成します。lightdash_mcp/tools/ 内に作成してください（例：my_new_tool.py）

2. ツールを定義します。

   from pydantic import BaseModel, Field
   from .base_tool import ToolDefinition
   from .. import lightdash_client as client
   
   class MyToolInput(BaseModel):
       param1: str = Field(..., description="Description of param1")
   
   TOOL_DEFINITION = ToolDefinition(
       name="my-new-tool",
       description="Description of what this tool does",
       input_schema=MyToolInput
   )
   
   def run(param1: str) -> dict:
       """ツールのロジックを実行します"""
       result = client.get(f"/api/v1/some/endpoint/{param1}")
       return result
   

3. サーバーを再起動します。ツールが自動的に登録されます

ツールレジストリ

ツールは tools/__init__.py を通じて自動的に検出されます。このファイルでは、次の処理を行います。

• tools/ ディレクトリ内の Python モジュールをスキャンします
• 各モジュールをインポートします（ユーティリティモジュールを除く）
• TOOL_DEFINITION.name に基づいてツールを登録します

テスト

個々のツールは、インポートしてテストできます。

from tools import tool_registry

# List all registered tools
print(tool_registry.keys())

# Test a specific tool
result = tool_registry['list-projects'].run()
print(result)

トラブルシューティング

認証エラー

401 Unauthorized エラーが表示される場合：

• LIGHTDASH_TOKEN が正しく、ldt_ で始まっていることを確認してください
• トークンの有効期限が切れていないことを確認してください
• Lightdash で必要な権限があることを確認してください

接続エラー

接続エラーが表示される場合：

• LIGHTDASH_URL が正しいことを確認してください
• Lightdash Cloud の場合：https://app.lightdash.cloud を使用してください
• セルフホストの場合：https://your-domain.com を使用してください
• Cloudflare Access の背後にある場合は、CF_ACCESS_CLIENT_ID と CF_ACCESS_CLIENT_SECRET が設定されていることを確認してください
• Google Cloud IAP の背後にある場合は、IAP_ENABLED=true が設定されていること、pip install lightdash-mcp[iap] でインストールされていること、サービスアカウント自身に serviceAccountTokenCreator が付与されていることを確認してください

ツールが見つからない場合

ツールが表示されない場合：

• ファイルが tools/ ディレクトリ内にあることを確認してください
• ファイルに TOOL_DEFINITION 変数があることを確認してください
• ファイルが tools/__init__.py の除外リストに含まれていないことを確認してください
• MCP サーバーを再起動してください

コントリビューション

コントリビューションを歓迎します。次の手順でお願いします。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 適切なテストを追加して変更を加えます
4. プルリクエストを送信します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

サポート

問題や質問がある場合：

• Lightdash Documentation
• Lightdash Community Slack
• MCP Documentation