metabase-ai-assistant

Metabase AI Assistant — Model Context Protocol（MCP）サーバー

Metabase AI Assistant は、LLM、AI コーディングアシスタント、自動化されたデータワークフローを、お使いの Metabase Business Intelligence インスタンスに直接接続するエンタープライズグレードの Model Context Protocol（MCP）サーバーです。

152 個の専用ツール、ネイティブの dbt Metadata & Metrics Auto-Syncer、Metabase から dbt への Reverse Lineage Exposures、dbt-Smart Question Creator、Lightdash Code-as-BI YAML-to-Dashboard 生成、Cube.js スタイルの Pre-aggregations と Multi-Hop Lineage Joins、Omni.co Controlled Semantic-to-YAML bridge、自律的な自己修復 SQL 実行、ダッシュボードの大規模な設計、プロアクティブな異常検知、クエリーインデックスのアドバイザリー、PII の漏えいゼロを実現するマスキング、厳格なセキュリティガードレールを備えています。Claude、Cursor、ChatGPT、Gemini、Google Antigravity とシームレスに連携します。

---

🌍 言語バージョン / 言語オプション / 言語バージョン / 言語版

• 🇬🇧 英語（メインドキュメント）
• 🇹🇷 トルコ語ドキュメント
• 🇨🇳 中国語ドキュメント（Chinese）
• 🇸🇦 アラビア語ドキュメント（Arabic）

---

目次

• アーキテクチャの主な特長
• 次世代の自律型機能（v5.3）
• Metabase のバージョン互換性
• クイックスタートとインストール
• クライアントの設定とデスクトップセットアップ
  • Claude Desktop（ワンクリック DXT と JSON）
  • Cursor IDE、Windsurf、VS Code
  • ChatGPT カスタム GPT と Actions
  • Google Gemini と AI Studio
  • Google Antigravity SDK と MCP
• ツールカテゴリの概要（152 個のツール）
• テストと品質保証
• プロジェクトのロードマップと今後の機能
• ライセンス

---

中核となるアーキテクチャの特長

Metabase AI Assistant は、標準的な AI インターフェース（Claude Desktop、Cursor、VS Code、ChatGPT、Gemini、自動化されたエージェントフレームワーク）を、Metabase をフル活用できる環境へと変えます。

1. dbt の詳細スキャンと MetricFlow の統合（dbt_project_scan_deep）：9 層のアーキテクチャ分類、doc('...') の解決、catalog.json によるテーブル／カラムのプロファイリングを実行します。
2. Cube.js の複数ホップのリネージ結合（dbt_lineage_joins_graph）：3 色 DAG サイクル検出を備えた Dijkstra Min-Heap アルゴリズムを使って、最短の結合パスを解決します。
3. Cube.js の事前集計とロールアップアドバイザー（dbt_semantic_preagg_advisor）：HyperLogLog の個別件数を含む、複数の SQL 方言に対応したマテリアライズドビューの DDL（Postgres、BigQuery、Snowflake、ClickHouse、DuckDB、Redshift、MySQL）を生成します。
4. Lightdash のコードを BI に変換するダッシュボードビルダー（dbt_build_dashboard_from_yaml）：meta.metabase と meta.lightdash の書式設定オプションを、重複のない 24 列の Metabase ダッシュボードに変換します。
5. Omni.co の制御されたセマンティックから YAML へのエクスポーター（dbt_semantic_export_yaml）：承認済みのビジネスルールを、整然とした dbt schema.yml／semantic_models.yml のコードブロックにシリアライズします。
6. 自律型自己修復 SQL エンジン（ai_sql_execute_and_heal）：堅牢なクエリを実現する、3 回の反復による自動エラー回復ループです。
7. 漏えいゼロのエンタープライズ向け PII マスキング：メールアドレス、電話番号、国民識別番号、クレジットカード、IP アドレス、トークンをリアルタイムでサニタイズします。

---

次世代の自律機能（v5.1）

1. dbt のアーキテクチャ階層とソースの優先順位付け

$$\mathbf{Gold;Marts;(fct_,;dim_,;rpt_)} ;\gg; \mathbf{Silver;(int_)} ;\gg; \mathbf{Bronze;Staging;(stg_)}$$

• dbt_inspect_models：dbt の manifest.json と MetricFlow のセマンティックモデルを解析します。
• dbt_prioritize_sources：自然言語での質問を、事前集計済みでテスト済みのディメンションテーブルおよびファクトテーブルへ動的に振り分けます。

2. ガバナンス優先のセマンティックメモリ（サイレントラーニングなし、完全削除なし）

• semantic_memory_propose：ビジネスルールを PENDING_APPROVAL ステータスで提案します。
• semantic_memory_approve：必須のデータスチュワードのコメントを付けて、ルールを明示的に有効化します。
• semantic_memory_deprecate：必須の監査理由を記録して、ルールを安全にソフトアーカイブします（DEPRECATED）。
• semantic_memory_restore：アーカイブ済みのルールを即座に復元します。
• semantic_memory_list：完全な監査履歴とタイムスタンプを含めて、すべてのルールを一覧表示します。

3. 自律型自己修復 SQL エンジン（ai_sql_execute_and_heal）

• Postgres、MySQL、BigQuery、Snowflake、SQLite における構文エラー、レーベンシュタイン距離に基づくカラム名の誤記、GROUP BY 句の不足、方言固有の違いを検出します。
• 修正履歴を _provenance.healing_trail に保持します。

---

Metabase のバージョン互換性

Metabase AI Assistant は、すべての主要な Metabase アーキテクチャで後方互換性と前方互換性を提供します。

Metabase のバージョン範囲	互換性レベル	サポートされる主な機能
Metabase v0.55 – v0.61+ (現行)	完全サポート	最新の MBQL 5 形式（stages、lib/type）、/api/upload/csv、更新されたコレクション権限、複数タブのダッシュボード
Metabase v0.50 – v0.54	完全サポート	コレクションツリー階層（/api/collection/tree）、モデルカード、API キー認証（x-api-key）、逐次的なパラメトリッククエリ
Metabase v0.43 – v0.49	完全サポート	セッショントークン認証（X-Metabase-Session）、レガシー MBQL クエリパイプライン、データベースのイントロスペクション
Metabase Open Source & Enterprise	完全サポート	機能の自動検出（ホワイトラベル、監査ログ、きめ細かなデータ権限）

---

クイックスタートとインストール

NPX によるグローバル実行

npx metabase-ai-assistant

NPM による手動インストール

npm install -g metabase-ai-assistant

---

クライアントの設定とデスクトップのセットアップ

1. Claude Desktop

オプション A：ワンクリック拡張機能（DXT / MCPB）

1. Claude Desktop Settings -> Developer / Extensions -> Install Local Extensionを開きます。
2. このリポジトリフォルダーを選択します。
3. または、Smithery CLIを使用してインストールします：

   npx -y @smithery/cli install metabase-ai-assistant --client claude
   

オプション B：手動での JSON 設定

サーバー定義をclaude_desktop_config.jsonに追加します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-ai-assistant"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "mb_your_api_key_here",
        "METABASE_READ_ONLY_MODE": "true"
      }
    }
  }
}

2. Cursor IDE、Windsurf、VS Code

.cursor/mcp.jsonまたはVS CodeのMCP設定に追加します：

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-ai-assistant"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "mb_your_api_key_here",
        "METABASE_READ_ONLY_MODE": "true"
      }
    }
  }
}

3. ChatGPTのカスタムGPTとアクション

Metabase AI AssistantをOpenAPIアクションとして公開し、ChatGPT Plus／Team／Enterpriseで利用できるようにします：

1. リモートSSE／HTTPサーバーを起動します：npm run start:sse
2. ChatGPTでカスタムGPT -> アクション -> URLからインポートを選択します：https://your-domain.com/tools/openapi.json
3. 詳細な設定ガイド：docs/integrations/CHATGPT_ACTIONS_GUIDE.md

4. Google GeminiとGoogle AI Studio

ツール定義をGemini Function Calling SDK（@google/genaiまたはgoogle-generativeai）に渡します：

• 詳細な設定ガイド：docs/integrations/GOOGLE_GEMINI_GUIDE.md

5. Cloudflare Workers（サーバーレスエッジ）

Cloudflareのエッジネットワークに直接、無料でデプロイします：

cd deploy/cloudflare
npx wrangler deploy

---

ツールカテゴリの概要（143個のツール）

143個のMCPツールは、10の運用領域に分類されています：

1. dbtとセマンティックレイヤー（6個のツール）：モデル階層の調査、リネージの解決、ソースの優先順位付け、ガバナンスを優先したビジネスメモリ（提案、承認、ソフト非推奨化、復元）。
2. 自律型AI BI運用（4個のツール）：自己修復SQLエンジン、エンドツーエンドのダッシュボード設計ツール、クエリインデックスアドバイザー、プロアクティブな異常検知ツール。
3. SQLとクエリ実行（14個のツール）：SQLクエリの直接実行、非同期実行ジョブ、クエリステータスの追跡、ページネーション、速度ベンチマーク。
4. AIクエリインテリジェンス（6個のツール）：自然言語からSQLへの変換、クエリパフォーマンスの最適化、クエリの説明、テーブル説明の自動作成。
5. カードとビジュアライゼーション（34個のツール）：質問の作成、クエリの実行、パラメーターによるフィルタリング、カードの複製、ビジュアライゼーション設定。
6. ダッシュボードとレイアウト（22個のツール）：ダッシュボードの作成、グリッドへの配置、フィルターのリンク、タブ管理、エグゼクティブ向けテンプレート。
7. コレクションと整理（8個のツール）：コレクションツリーの走査、階層内での移動、権限グラフ、項目一覧。
8. スキーマとデータモデリング（18個のツール）：スキーマの取得、外部キーの推定、データプロファイリング、テーブル定義。
9. ユーザーと権限の管理（12個のツール）：ユーザーの招待、グループへの割り当て、メンバーシップの管理、ステータスの切り替え。
10. アクションとドキュメント（19個のツール）：Metabaseアクションの実行、パルス、アラート、Webhook、メトリクス、セグメント定義、ワークスペースの移行。

---

テストと品質保証

ユニットロジック、統合ワークフロー、セキュリティファジングを網羅する、自動化された多層テストスイートに支えられています：

# Run complete test suite (32 suites, 583 tests)
npm test

# Run unit tests
npm run test:unit

# Run integration workflows
npm run test:integration

# Run security & PII zero-leak fuzzing tests
npm run test:security

---

ライセンス

Apache License 2.0の下でライセンスされています。詳細はLICENSEファイルをご覧ください。

Abdullah Enes SARI（ONMARTECH LLC）が開発・保守しています。