Metabase Ai Assistant

🚀 Metabase AI Assistant 🤖

AIによって駆動されるアシスタントで、Model Context Protocol (MCP) を介して Metabase と PostgreSQLデータベース に直接接続し、Claude Desktop と Claude Code で使用できます。Metabase APIと直接のデータベース接続の両方を利用して、モデル、SQLクエリ、メトリック、およびダッシュボードを作成します。

🚀 Claude DesktopとClaude Code用のMCPサーバー - Metabase + 直接のデータベースアクセス
⭐ このプロジェクトが役に立った場合は、スターをつけてください！ ⭐

🚀 クイックスタート

このセクションでは、Metabase AI Assistantをすぐに使い始めるための手順を説明します。

✨ 主な機能

🔌 MCP統合 (Claude Desktop & Claude Code)

• Model Context Protocol：Claude DesktopとClaude Codeとのネイティブ統合
• 直接のデータベースアクセス：直接のPostgreSQLデータベース接続
• Metabase API統合：Metabaseインスタンスとの完全な統合
• スキーマ探索：自動的なデータベーススキーマの探索と分析
• リレーションシップ検出：テーブル間のリレーションシップの検出と提案

🤖 AIによる機能

• 自然言語SQL：自然言語の説明からSQLクエリを生成
• スマートモデル構築：AIによる支援を受けたMetabaseモデルの作成
• インテリジェントダッシュボード：自動的なダッシュボードのレイアウトとウィジェットの提案
• クエリ最適化：SQLクエリのパフォーマンス最適化
• データインサイト：データ分析とパターン検出

🛠️ 開発者ツール

• DDL操作：安全なテーブル/ビュー/インデックスの作成（プレフィックス保護）
• バッチ操作：大量のデータ処理操作
• 接続管理：ハイブリッド接続管理（API + 直接）
• セキュリティコントロール：AIオブジェクトのプレフィックス制御と承認ワークフロー
• パフォーマンスモニタリング：操作のタイミングとタイムアウト制御

📋 必要条件

🖥️ システム

• Node.js 18+
• Claude Desktop (MCPサポート用) または Claude Code
• PostgreSQLデータベース (直接接続用)

🔗 サービス

• Metabaseインスタンス (v0.48+)
• Anthropic API (Claude Desktop/Codeに含まれる)

📦 インストール

# リポジトリをクローン
git clone https://github.com/onmartech/metabase-ai-assistant.git
cd metabase-ai-assistant

# 依存関係をインストール
npm install

# 環境ファイルを作成
cp .env.example .env

⚙️ 設定

.env ファイルを編集します。

# Metabase設定
METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_metabase_api_key

# AIプロバイダー (少なくとも1つ必要)
ANTHROPIC_API_KEY=your_anthropic_key
# または
OPENAI_API_KEY=your_openai_key

# アプリケーション設定
LOG_LEVEL=info

⚠️ 重要提示

.env ファイルをバージョン管理にコミットしないでください。このファイルはすでに .gitignore に含まれています。

🔌 Claude DesktopとClaude Codeの統合 (MCP)

このプロジェクトは、Model Context Protocol (MCP) を介してClaude DesktopとClaude Codeと統合されています。

Claude Desktopの場合

1. Claude Desktopの設定を編集：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-ai-assistant": {
      "command": "node",
      "args": ["/path/to/your/metabase-ai-assistant/src/mcp/server.js"],
      "env": {
        "METABASE_URL": "http://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password",
        "ANTHROPIC_API_KEY": "your_anthropic_key"
      }
    }
  }
}

2. Claude Desktopを再起動 すると、MCPツールが利用可能になります。

Claude Codeの場合

Claude Codeは、グローバルインストールを介してこのMCPサーバーを直接使用できます。

ステップ1: グローバルインストール

# MCPサーバーをグローバルにインストール
npm link

# インストールを確認
which metabase-ai-mcp
npm list -g | grep metabase-ai-assistant

ステップ2: 環境設定

.env ファイルがMetabaseの資格情報で適切に設定されていることを確認します。

METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_api_key
ANTHROPIC_API_KEY=your_anthropic_key

ステップ3: MCPサーバーをテスト

# MCPサーバーを直接テスト
node src/mcp/server.js

# 環境変数を使用してテスト
export METABASE_URL="http://your-instance.com"
export METABASE_USERNAME="your_username"
export METABASE_PASSWORD="your_password"
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node src/mcp/server.js

ステップ4: 統合を確認

Claude Codeで、"What MCP tools do you have available?" と尋ねます。

27個のMetabase AI Assistantツール が利用可能であることが表示されます。

📊 データベースツール:

• db_list - すべてのMetabaseデータベースをリストする
• db_schemas - スキーマ情報を取得する
• db_tables - 詳細を含むテーブルをリストする
• sql_execute - SQLクエリを実行する

🎯 Metabaseツール:

• mb_question_create - 質問/チャートを作成する
• mb_dashboard_create - ダッシュボードを作成する
• mb_dashboard_template_executive - エグゼクティブダッシュボードを自動生成する
• mb_question_create_parametric - パラメトリックな質問を作成する

🔍 AIによるツール:

• ai_sql_generate - 自然言語からSQLを生成する
• ai_sql_optimize - SQLのパフォーマンスを最適化する
• ai_sql_explain - SQLクエリを説明する

📚 ドキュメントツール:

• web_explore_metabase_docs - Metabaseのドキュメントをクロールする
• web_search_metabase_docs - ドキュメントを検索する

サーバーは、27個のツール を提供し、以下のことができます。

• データベーススキーマの探索と分析
• 自然言語によるSQLクエリの生成と最適化
• エグゼクティブダッシュボードのテンプレートとパラメトリックな質問
• セキュリティコントロール付きの直接のDDL操作
• Metabaseドキュメントのクロールと検索
• テーブルのリレーションシップの検出とマッピング

💻 使用例

対話型CLI

npm start

プログラムによる使用

import { MetabaseClient } from './src/metabase/client.js';
import { MetabaseAIAssistant } from './src/ai/assistant.js';

// クライアントを作成
const client = new MetabaseClient({
  url: 'http://your-metabase.com',
  username: 'user',
  password: 'pass'
});

// AIアシスタントを起動
const assistant = new MetabaseAIAssistant({
  metabaseClient: client,
  aiProvider: 'anthropic',
  anthropicApiKey: 'your-key'
});

// モデルを作成
const model = await assistant.createModel(
  'Müşteri segmentasyon modeli',
  databaseId
);

// SQLクエリを生成
const sql = await assistant.generateSQL(
  'Son 30 günün satış toplamı',
  schema
);

基本的な使用法

以下のコードは、MetabaseClientとMetabaseAIAssistantを使ってモデルを作成し、SQLクエリを生成する基本的な例です。

import { MetabaseClient } from './src/metabase/client.js';
import { MetabaseAIAssistant } from './src/ai/assistant.js';

// クライアントを作成
const client = new MetabaseClient({
  url: 'http://your-metabase.com',
  username: 'user',
  password: 'pass'
});

// AIアシスタントを起動
const assistant = new MetabaseAIAssistant({
  metabaseClient: client,
  aiProvider: 'anthropic',
  anthropicApiKey: 'your-key'
});

// モデルを作成
const model = await assistant.createModel(
  'Müşteri segmentasyon modeli',
  databaseId
);

// SQLクエリを生成
const sql = await assistant.generateSQL(
  'Son 30 günün satış toplamı',
  schema
);

高度な使用法

高度なシナリオでは、複数の操作を組み合わせて、より複雑なタスクを実行できます。

// 例えば、モデル作成、質問作成、ダッシュボード作成を組み合わせる
await assistant.createModel('新しいモデル', databaseId);
await assistant.createQuestion('特定の質問', databaseId, collectionId);
await assistant.createDashboard('新しいダッシュボード', questions);

📚 ドキュメント

1. 電子商取引ダッシュボード

// 販売モデルを作成
await assistant.createModel(
  'Günlük satış özeti - ürün, kategori, tutar',
  databaseId
);

// メトリックを定義
await assistant.createMetric(
  'Ortalama sepet değeri',
  tableId
);

// ダッシュボードを作成
await assistant.createDashboard(
  'E-Ticaret Yönetici Paneli',
  questions
);

2. 顧客分析

// 顧客セグメンテーションクエリ
const sql = await assistant.generateSQL(
  'RFM analizi ile müşteri segmentleri',
  schema
);

// 顧客離脱予測モデル
await assistant.createModel(
  'Müşteri kayıp tahmin modeli',
  databaseId
);

3. 財務報告

// 収益と費用の分析
await assistant.createQuestion(
  'Aylık kar-zarar tablosu',
  databaseId
);

// 予算比較ダッシュボード
await assistant.createDashboard(
  'Bütçe vs Gerçekleşen',
  budgetQuestions
);

🛠️ CLIコマンド

対話型CLIで使用できるコマンドは次の通りです。

• 📊 モデルを作成：AIを使用してモデルを作成する
• ❓ 質問を作成：SQLクエリを作成する
• 📈 メトリックを作成：メトリックを定義する
• 📋 ダッシュボードを作成：ダッシュボードを準備する
• 🔍 スキーマを探索：データベーススキーマを調査する
• 🚀 SQLを実行：SQLクエリを実行する
• 🔧 クエリを最適化：クエリを最適化する
• 💡 AIクエリビルダー：自然言語でクエリを作成する

📂 プロジェクト構造

metabase-ai-assistant/
├── src/
│   ├── mcp/
│   │   └── server.js        # MCPサーバー (Claude Desktop統合)
│   ├── metabase/
│   │   └── client.js        # Metabase APIクライアント
│   ├── database/
│   │   ├── direct-client.js     # 直接のPostgreSQLクライアント
│   │   └── connection-manager.js # ハイブリッド接続管理
│   ├── ai/
│   │   └── assistant.js     # AIヘルパー関数
│   ├── cli/
│   │   └── interactive.js   # 対話型CLI (スタンドアロン)
│   ├── utils/
│   │   └── logger.js        # ロギングユーティリティ
│   └── index.js             # メインエントリポイント (CLIモード)
├── tests/                    # テストファイル
├── .env.example             # 環境テンプレート
├── package.json
└── README.md

🔍 APIリファレンス

MetabaseClient

// データベース
getDatabases()
getDatabase(id)
getDatabaseSchemas(databaseId)
getDatabaseTables(databaseId)

// モデル
getModels()
createModel(modelData)

// クエリ
getQuestions(collectionId)
createQuestion(questionData)
executeNativeQuery(databaseId, sql)

// メトリック
getMetrics()
createMetric(metricData)

// ダッシュボード
getDashboards()
createDashboard(dashboardData)
addCardToDashboard(dashboardId, cardId, options)

MetabaseAIAssistant

// AI操作
analyzeRequest(userRequest)
generateSQL(description, schema)
suggestVisualization(data, questionType)
optimizeQuery(sql)
explainQuery(sql)

// 作成操作
createModel(description, databaseId)
createQuestion(description, databaseId, collectionId)
createMetric(description, tableId)
createDashboard(description, questions)

🧪 テスト

# すべてのテストを実行
npm test

# 接続テスト
npm run test:connection

# カバレッジレポート
npm run test:coverage

🔒 セキュリティ

データセキュリティ

• 環境変数：すべての機密データ（APIキー、パスワード）は .env ファイルに保存されます。
• Git Ignore：.env ファイルはバージョン管理から除外されています。
• SQLインジェクション防止：パラメータ化されたクエリと入力検証が行われます。
• レート制限：APIリクエストにレート制限が適用されます。
• 監査ログ：すべてのデータベース操作がセキュリティ監視のためにログに記録されます。
• ハードコードされた資格情報なし：セキュリティを重視したアプローチにより、資格情報の露出を防ぎます。

データベースセキュリティ

• AIオブジェクトプレフィックス：すべてのAIによって作成されたオブジェクトは、安全のために claude_ai_ プレフィックスが付けられます。
• スキーマ分離：操作は指定されたスキーマに限定されます。
• 読み取り専用モード：デフォルトで読み取り専用の権限が設定され、変更には明示的な承認が必要です。
• DDL承認システム：データベースの変更には明示的な確認が必要です。
• プレフィックス検証：AIプレフィックスが付けられたオブジェクトのみが変更または削除できます。

MCPセキュリティ

• 安全なトランスポート：MCP通信は安全なチャネルを介して行われます。
• 環境分離：資格情報は環境変数を介して渡されます。
• ツール検証：すべてのツールの入力は実行前に検証されます。
• エラーハンドリング：エラーメッセージから機密情報がフィルタリングされます。

本番環境へのデプロイ

• 環境固有の設定ファイルを使用します。
• すべてのデータベース通信にSSL/TLS接続を使用することを推奨します。
• データベースユーザーには必要最小限の権限を付与します。
• APIエンドポイントを認証と承認で保護します。
• APIキーとデータベースパスワードを定期的に更新します。
• すべてのツールの使用を監視し、ログを記録してセキュリティ監査を行います。

🐛 トラブルシューティング

接続エラー

• MetabaseのURLがアクセス可能であることを確認します。
• APIキーと資格情報が有効であることを確認します。
• ネットワーク接続とファイアウォールの設定を確認します。
• 環境変数が適切に設定されていることを確認します。

MCP統合の問題

• npm link が正常に実行されたことを確認します。
• MCPサーバーのバイナリがPATHに含まれていることを確認します：which metabase-ai-mcp
• 環境変数がエクスポートされていることを確認します：echo $METABASE_URL
• MCPサーバーを直接テストします：node src/mcp/server.js
• グローバルインストール後にClaude Codeを再起動します。

クエリエラー

• SQL構文と書式を検証します。
• テーブル名と列名が存在することを確認します。
• データベースの権限とスキーマへのアクセスを確認します。
• 操作に適切なスキーマが選択されていることを確認します。

セキュリティ警告

• .env ファイルをバージョン管理にコミットしないでください。
• ソースコードにハードコードされた資格情報を使用しないでください。
• AIによって作成されたオブジェクトにはプレフィックス検証を使用します。
• データベース操作をセキュリティコンプライアンスのために監視します。

🚀 本番環境へのデプロイ

オプション1: PM2プロセスマネージャー (推奨)

# PM2をグローバルにインストール
npm install -g pm2

# PM2でMCPサーバーを起動
npm run pm2:start

# 監視と管理
npm run pm2:logs
npm run pm2:restart
npm run pm2:stop

# システム再起動時に自動起動
pm2 startup
pm2 save

オプション2: Dockerコンテナ

# Docker Composeでビルドして実行
npm run docker:run

# ログを監視
npm run docker:logs

# コンテナを停止
npm run docker:stop

オプション3: クラウドデプロイ

• Railway：railway.json を使用してワンクリックでデプロイできます。
• Heroku：Heroku CLIを使用してデプロイします (詳細は deploy/heroku-deploy.md を参照)。
• DigitalOcean：Dockerを使用したApp Platform。
• AWS：ECS FargateまたはEC2とsystemdサービス。

オプション4: systemdサービス (Linux)

# サービスファイルをコピー
sudo cp metabase-ai-mcp.service /etc/systemd/system/

# サービスを有効化して起動
sudo systemctl enable metabase-ai-mcp
sudo systemctl start metabase-ai-mcp

# サービスを監視
sudo systemctl status metabase-ai-mcp
sudo journalctl -u metabase-ai-mcp -f

本番環境用スクリプト

npm run mcp:prod          # 本番モード
npm run test:connection   # ヘルスチェック
npm run lint             # コード品質チェック

📈 ロードマップ

• [ ] 自然言語処理の改善
• [ ] 視覚的なクエリビルダー
• [ ] 自動ダッシュボード推奨システム
• [ ] マルチデータベースサポート
• [ ] リアルタイムデータストリーミング
• [ ] 高度な機械学習モデル

🤝 貢献方法

このプロジェクトを気に入って、開発に貢献したい場合は、以下の方法があります。

⭐ プロジェクトをサポートする

• GitHubでスターを付ける：プロジェクトが役に立った場合は ⭐ スターを付けてください。
• フォローする：更新情報を得るために @onmartech をフォローしてください。
• 共有する：ソーシャルメディアで共有し、友人におすすめしてください。

🔧 開発に参加する

1. Fork します。
2. Feature branch を作成します (git checkout -b feature/yeni-ozellik)。
3. 変更をコミット します (git commit -m 'feat: Yeni özellik eklendi')。
4. Push します (git push origin feature/yeni-ozellik)。
5. Pull Request を作成します。

💡 貢献のアイデア

• 新しいAIモデルの統合
• ダッシュボードテンプレート
• Metabaseコネクター
• ドキュメントの改善
• バグ修正とパフォーマンス最適化

📋 貢献のルール

• コードの変更にはテストを書いてください。
• コミットメッセージには Conventional Commits を使用してください。
• ESLintとPrettierの設定に従ってください。
• 変更内容をドキュメント化してください。

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。 Copyright (c) 2024 ONMARTECH LLC

👥 サポートと連絡先

🐛 バグ報告と機能リクエスト

• GitHub Issues：Issuesページ
• バグテンプレート：Issueを作成する際にテンプレートを使用してください。
• 機能リクエスト：必要な機能を詳細に説明してください。

💬 コミュニティ

• GitHub Discussions：質問やアイデアを共有するための場所です。
• ドキュメント：Wikiページに貢献してください。
• 使用例：使用ケースを共有してください。

🚀 商用サポート

ONMARTECH LLCから専門的なサポートとカスタマイズサービスを利用できます。

🏆 貢献者

このプロジェクトを可能にしたすべての人に感謝します。

• ONMARTECH LLC - プロジェクトの開発と保守
• Metabaseチーム - 素晴らしいプラットフォーム
• オープンソースコミュニティ - 常にインスピレーションとフィードバックを提供してくれます。

🌟 名誉の殿堂

重要な貢献をした開発者はここにリストされます。

このプロジェクトが役に立った場合は、⭐ スターを付けて、🔄 共有することを忘れないでください！