📊 Metabase MCP Server

📊 Metabase MCP サーバー

📚 目次

1. このツールについて
2. 動画での解説
3. アーキテクチャ図
4. はじめに
   • Metabase のセットアップ
   • uv パッケージマネージャーのインストール
   • リポジトリのクローンまたはダウンロード
   • 依存関係のインストール
   • 認証情報の設定
   • MCP クライアントへの接続
5. 設定オプション
6. Metabase API キーの取得
7. DXT ファイルのサポート
8. 独自の DXT ファイルを作成する方法
9. リモートデプロイ
10. MCP Inspector によるデバッグ
11. 利用可能なツール
12. 試してみるためのプロンプト例
13. お問い合わせ
14. ライセンス

---

😊 このツールについて

Metabase MCP Server は、Model Context Protocol（MCP） を使用して、Metabase インスタンスと AI アシスタント を接続するバックエンド統合レイヤーです。これにより、ビジネスリーダー、プロダクトマネージャー、アナリストは、任意の MCP クライアント（例：Claude Desktop）を通じて、自然言語でダッシュボードやチャートなどのビジネスインテリジェンス資産を操作できます。

メニューを移動したり、SQL クエリを手作業で作成したりする代わりに、次のことができます。

• 質問して、すぐに分析結果を得られます。
• 希望する内容を説明して、ダッシュボードやチャートを作成できます。
• 簡単な指示で、ユーザーアクセスやデータベース接続を管理できます。

このプロジェクトにより、Metabase は単なるダッシュボード作成ツールではなく、会話形式でやり取りできるインテリジェントなビジネスアシスタントになります。

---

🎥 動画での解説

Metabase MCP Server の動作を紹介する動画をご覧ください。

---

📐 アーキテクチャ図

---

🚀 はじめに

1. Metabase のセットアップ（まだの場合）

Metabase の公式インストールガイドに従ってください：Metabase ドキュメント

2. uv パッケージマネージャーのインストール

Python とパッケージ管理機能を含む uv をインストールします。

Windows：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

または、パッケージマネージャーを使ってインストールします。

# macOS
brew install uv

# Windows (via Scoop)
scoop install uv

# Windows (via Chocolatey)
choco install uv

uv のインストールと使用方法の詳細については、公式ドキュメントをご覧ください：https://docs.astral.sh/uv/getting-started/installation/

3. リポジトリのクローンまたはダウンロード

このツールをお使いのコンピューターに入手する必要があります。手動でダウンロードするか、Git を使用できます。 コンピューターのターミナル（Mac）またはコマンドプロンプト（Windows）を開きます。 ファイルを展開したフォルダー、またはプロジェクトをクローンするフォルダーに移動します。

# Example (replace with your actual path):
cd ~/Downloads/metabase-mcp-server-dev

方法 1：ZIP をダウンロード

1. GitHub リポジトリに移動します
2. 緑色の 「Code」 ボタンをクリックします
3. 「Download ZIP」 を選択します
4. ダウンロードしたファイルを Documents フォルダーなどに展開します

方法 2：Git を使用 Git に慣れている場合は、ターミナルで次のコマンドを実行します。

git clone https://github.com/CW-Codewalnut/Metabase-MCP-Server.git
cd Metabase-MCP-Server

4. 依存関係のインストール

このコマンドにより、次の処理が自動的に行われます。

• 必要な Python バージョンをインストールします（まだ利用できない場合）
• プロジェクト用の仮想環境を作成します
• 必要なすべてのパッケージと依存関係をインストールします

uv sync

5. 認証情報を設定する

MCP サーバーの Metabase 認証情報を設定する方法は 3 つあります。

オプション 1：.env ファイルを使用する（推奨） プロジェクトのルートに .env ファイルを作成します。

METABASE_URL=http://localhost:3000
METABASE_API_KEY=mb_xxx_your_key
PORT=3200
HOST=localhost
TRANSPORT=streamable-http
LOG_LEVEL=INFO

オプション 2：コマンドライン引数を使用する コマンドラインから直接設定を渡します。

uv run src/metabase_mcp_server.py --metabase-url http://localhost:3000 --metabase-api-key "YOUR_API_KEY" --port 3200 --host localhost --transport streamable-http --log-level INFO

オプション 3：MCP クライアント設定で環境変数を使用する .env ファイルを使わずに、MCP クライアントで直接設定します（以下の例を参照してください）。

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"
      ],
      "env": {
        "METABASE_URL": "http://localhost:3000",
        "METABASE_API_KEY": "mb_xxx_your_key",
        "PORT": 3200,
        "HOST": "localhost",
        "TRANSPORT": "streamable-http",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

6. MCP クライアントに接続する

Claude Desktop アプリ、Claude Code、Cursor、Windsurf など、お好みの MCP クライアントを選び、それぞれの設定ファイルに Metabase MCP サーバーを追加します。すべての MCP クライアントで、同様の設定パターンを使用します。

設定例

stdio トランスポートの場合（ローカル MCP サーバーに推奨）：

Windows：

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"
      ]
    }
  }
}

Mac：

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "/Users/YourName/Projects/metabase-mcp-server/.venv/bin/python",
      "args": [
        "/Users/YourName/Projects/metabase-mcp-server/src/metabase_mcp_server.py"
      ]
    }
  }
}

主な違い：

• Windows ではパスに バックスラッシュ \\ を使用します
• macOS/Linux ではパスに スラッシュ / を使用します
• エラーを避けるため、お使いの OS に合った形式を使用してください

重要な注意事項：

• FULL_PATH をプロジェクトディレクトリの実際の絶対パスに置き換えてください
• 設定の変更を保存した後、新しい設定を適用するために MCP クライアントを再起動してください
• Cursor でプロジェクト固有のツールを使用するには、プロジェクトディレクトリに .cursor/mcp.json ファイルを作成します
• Cursor でグローバルツールを使用するには、ホームディレクトリに ~/.cursor/mcp.json ファイルを作成します

streamable-http トランスポートの場合（リモート MCP サーバーに推奨）：

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://localhost:3200/mcp/"
    }
  }
}

互換性のある MCP クライアント

各クライアントをクリックして、公式の MCP 設定ドキュメントをご覧ください。

クライアント	公式 MCP ドキュメント
	Claude Desktop 向け Anthropic 公式 MCP ガイド
	Claude Code の公式 MCP 設定ドキュメント
	Cursor の公式 MCP 設定ガイド
	Windsurf の公式 MCP 設定ドキュメント
	Cline の公式 MCP クイックスタートガイド
	VS Code Copilot の MCP サーバー設定

設定を追加すると、MCP クライアントに MCP サーバーが表示されます。

---

🔧 設定オプション

Metabase MCP Server は、環境変数、コマンドライン引数、またはその両方を組み合わせて柔軟に設定できます。

環境変数

Variable	Description	Default Value	Example
METABASE_URL	Metabase インスタンスの URL	必須	http://127.0.0.1:3000
METABASE_API_KEY	Metabase API キー	必須	mb_xxx_your_api_key
TRANSPORT	トランスポートプロトコル	stdio	stdio, sse, streamable-http
HOST	HTTP トランスポートのホスト	localhost	0.0.0.0, 127.0.0.1
PORT	HTTP トランスポートのポート	3200	8080, 9000
LOG_LEVEL	ログレベル	INFO	DEBUG, INFO, WARNING, ERROR

コマンドライン引数

Argument	Description	Options	Default Value
--metabase-url	Metabase インスタンスの URL	任意の Metabase URL	必須
--metabase-api-key	Metabase API キー	mb_... キー	必須
--transport	トランスポートプロトコル	stdio, sse, streamable-http	stdio
--host	HTTP トランスポートのホスト	任意のホストまたは IP	localhost
--port	HTTP トランスポートのポート	任意のポート番号	3200
--log-level	ログの詳細レベル	DEBUG, INFO, WARNING, ERROR	INFO

トランスポートプロトコル

Protocol	Description	Use Case
stdio	標準入出力による通信	ローカル統合に最適です（Claude Desktop、Cursor など）。
streamable-http	HTTP ベースのストリーミングプロトコル	リモート環境へのデプロイやウェブベースの統合に最適です。
sse	HTTP 経由の Server-Sent Events	⚠️ 非推奨 — 新しい設定では推奨されません

設定の優先順位

設定値は、次の優先順位（高い順）で適用されます。

1. コマンドライン引数（すべてを上書きします）
2. 環境変数（デフォルト値を上書きします）
3. デフォルト値

コマンドの完全な例

uv run src/metabase_mcp_server.py --transport streamable-http --host localhost --port 3200 --metabase-url http://127.0.0.1:3000 --metabase-api-key mb_xxx_your_key

注： サーバーの実行時に、すべてのパラメーターを指定する必要はありません。ただし、Metabase URL と API キーは必ず指定してください。指定されていないパラメーターには、上記のデフォルト値が使用されます。

---

🔑 Metabase API キーの取得

Metabase API キーを取得するには、次の手順に従います。

1. Metabase インスタンスにログインします
2. プロフィール画像をクリックします（右上隅）
3. 「Account settings」を選択します
4. 「API Keys」タブに移動します
5. 「Create API Key」をクリックします
6. キーにわかりやすい名前を付けます（例：「MCP Server Key」）
7. 生成されたキーをコピーします（mb_ で始まります）

⚠️ 重要： API キーは安全に保管し、バージョン管理に絶対にコミットしないでください。このキーを使うと、Metabase インスタンスに完全にアクセスできます。

---

📂 DXT ファイルのサポート

リポジトリのクローンや環境のセットアップの手順を実行する必要はなくなりました。以下の手順に従って、Claude Desktop App に Metabase MCP Server をインストールしてください。

1. DXT ファイルをダウンロードする
   以下のリンクから最新の DXT ファイル を直接ダウンロードしてください。
   DXT ファイルをダウンロード

2. Claude Desktop App を開く
   ファイルを入手したら、お使いのシステムで Claude Desktop App を開きます。

3. 拡張機能の設定に移動する
   Claude Desktop App で、次の操作を行います。

   • Files → Settings → Extensions に移動します。
   • 次に、Advanced Settings をクリックします。

4. DXT ファイルを選択する
   Advanced Settings セクションで、Choose File をクリックし、ダウンロードした DXT ファイル を選択します。

5. 必要な情報を入力する
   DXT ファイル を選択すると、必要な情報の入力を求めるプロンプトが表示されます。

   • Metabase URL：Metabase サーバーの URL を入力します。
   • API Key：認証用の該当する API キーを追加します。

6. セットアップを完了する
   必要な情報を入力したら、Save をクリックして設定を適用します。

これで完了です。Metabase MCP Server がインストールされ、Claude Desktop App で使用できるようになりました。

独自の DXT ファイルを作成する方法

独自の DXT ファイル を作成する場合は、公式ガイドをご覧ください。
独自の DXT ファイルを作成する

🚀 リモートデプロイ

本番環境での使用やチームでの共同作業のために、Metabase MCP Server をリモートデプロイできます。Codewalnut では社内でこの方法を使用しています。

Docker によるデプロイ

リモートデプロイを簡単に行えるよう、Docker 設定ファイルを用意しています。

Docker ですぐに始める

# Build the Docker image
docker build -t metabase-mcp-server .

# Run with environment variables
docker run -d \
  -p 3200:3200 \
  -e METABASE_URL="http://your-metabase-instance.com" \
  -e METABASE_API_KEY="mb_xxx_your_api_key" \
  metabase-mcp-server

Docker Compose（推奨）

version: "3.8"
services:
  metabase-mcp:
    build: .
    ports:
      - "3200:3200"
    environment:
      - METABASE_URL=http://your-metabase-instance.com
      - METABASE_API_KEY=mb_xxx_your_api_key
      ##- PORT=3200
      ##- HOST=localhost
      ##- TRANSPORT=streamable-http
      ##- LOG_LEVEL=INFO
    restart: unless-stopped

リモートの HTTP/SSE トランスポートは、デフォルトで読み取り専用です。一致する ALLOW_* 環境変数を true に設定するのは、サーバーが信頼できるアクセス制御の背後にあり、 設定された Metabase API キーに変更を行う権限がある場合に限ってください。 対象となる環境変数は、ALLOW_WRITE_TOOLS、ALLOW_ADMIN_TOOLS、および ALLOW_SQL_TOOL です。

リモート MCP サーバーへの接続

デプロイ後、リモートサーバーに接続するよう MCP クライアントを設定します。

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://server-ip:3200/mcp/"
    }
  }
}

デプロイの選択肢

• クラウドプロバイダー： AWS ECS、Google Cloud Run、Azure Container Instances
• VPS／専用サーバー： DigitalOcean、Linode、Vultr
• コンテナプラットフォーム： Kubernetes、Docker Swarm
• サービスとしてのプラットフォーム： Railway、Render、Fly.io

セキュリティに関する考慮事項

• 本番環境では HTTPS を使用してください
• 適切なファイアウォールルールを設定してください
• 機密性の高い業務データには VPN アクセスを検討してください
• API キーを定期的にローテーションしてください
• アクセスログを監視してください

デプロイについてお困りですか？

CodeWalnut のチームでは、デプロイおよびコンサルティングサービスを提供しています。エンタープライズグレードのセットアップとサポートについては、お問い合わせください。

---

🔍 MCP Inspector によるデバッグ

Metabase MCP Server のセットアップをデバッグしてテストするには、公式の MCP Inspector ツールを使用できます。

前提条件

まだインストールしていない場合は、まず Node.js をインストールしてください。

• ダウンロード先： nodejs.org

• または、パッケージマネージャーでインストール：

  # macOS
  brew install node
  
  # Windows (via Chocolatey)
  choco install nodejs
  
  # Windows (via Scoop)
  scoop install nodejs
  

MCP Inspector のインストールと実行

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your Metabase MCP Server
npx @modelcontextprotocol/inspector uv run FULL_PATH/metabase-mcp-server/src/metabase_mcp_server.py

MCP Inspector の使用

MCP Inspector では、次のことができます。

• リアルタイムのツールテスト - ウェブインターフェースから MCP ツールを直接実行できます
• リクエスト／レスポンスの監視 - 送受信されるデータを正確に確認できます
• エラーのデバッグ - 設定や API の問題をすばやく特定できます
• スキーマの検証 - ツールが正しく定義されていることを確認できます

起動後、ブラウザーで http://localhost:5173 を開くと、Inspector のインターフェースにアクセスできます。

よくあるデバッグのケース

• 接続の問題 - Metabase URL と API キーを確認してください
• 権限エラー - API キーに必要な権限があるか確認してください

---

🔧 利用可能なツール

Function	Description
コレクション操作
get_metabase_collection	IDでコレクションを取得します
create_metabase_collection	新しいコレクションを作成します
update_metabase_collection	コレクションのメタデータを更新します
delete_metabase_collection	コレクションを削除します
チャート（カード）操作
get_metabase_cards	すべてのチャートを一覧表示します
get_card_query_results	チャートクエリの結果を取得します
create_metabase_card	新しいチャートを作成します
update_metabase_card	既存のチャートを更新します
delete_metabase_card	チャートを削除します
ダッシュボード操作
get_metabase_dashboards	すべてのダッシュボードを一覧表示します
get_dashboard_by_id	IDでダッシュボードを取得します
get_dashboard_cards	ダッシュボード内のカードを取得します
get_dashboard_items	すべてのダッシュボード項目を取得します
create_metabase_dashboard	ダッシュボードを作成します
update_metabase_dashboard	ダッシュボードを更新します
delete_metabase_dashboard	ダッシュボードを削除します
copy_metabase_dashboard	既存のダッシュボードのコピーを作成します
データベース操作
get_metabase_databases	データベースを一覧表示します
create_metabase_database	新しいデータベース接続を作成します
update_metabase_database	データベース接続を更新します
delete_metabase_database	データベース接続を削除します
ユーザー操作
get_metabase_users	すべてのユーザーを一覧表示します
get_metabase_current_user	現在のユーザーの詳細を取得します
create_metabase_user	新しいユーザーを作成します
update_metabase_user	ユーザー情報を更新します
delete_metabase_user	ユーザーを削除します
グループ操作
get_metabase_groups	ユーザーグループを一覧表示します
create_metabase_group	ユーザーグループを作成します
delete_metabase_group	ユーザーグループを削除します
SQL操作
execute_sql_query	ネイティブSQLクエリを実行します

---

🧪 試してみるプロンプト

• 「Flight Overview」という名前のダッシュボードを作成し、出発地別のフライト数を棒グラフで表示します。
• SQLを実行します：SELECT origin, destination, COUNT(*) FROM flights GROUP BY origin, destination LIMIT 10。
• 地域別にグループ化した先月の予約総数を表示するカードを作成します。
• 「Abandoned Queries」という名前のチャートを削除します。
• 「Sales KPIs」ダッシュボードに新しい収益カードを追加します。
• 「Admin」グループのすべてのユーザーを表示します。
• 「Finance Analysts」という名前の新しいグループを作成します。
• Supabaseデータベースに接続し、すべてのテーブルを一覧表示します。

---

🌐 お問い合わせ

コミュニティの各チャネルを通じて、最新情報の確認やサポートの利用ができます。

🏢 公式リンク

• 🌍 ウェブサイト： codewalnut.com
• 📧 メール： [email protected]
• 📖 ブログ：
  • insights： codewalnut.com/insights
  • learn： codewalnut.com/learn

📱 ソーシャルメディア

• 💼 LinkedIn: CodeWalnut
• 📺 YouTube: CodeWalnut チャンネル
• 🐦 Twitter/X: @codewalnut
• 📷 Instagram: @codewalnut

💬 コミュニティサポート

• 📧 ニュースレター: CodeWalnut ニュースレターに登録（メール登録オプションを見つけるには、ページを下にスクロールしてください）
• 🐙 GitHub: codewalnut

🤝 プロフェッショナルサービス

• コンサルティング: Metabase のカスタム統合と AI ソリューション
• トレーニング: MCP およびビジネスインテリジェンスのワークショップ
• サポート: エンタープライズレベルのサポートとメンテナンス

📢 新しい MCP サーバー、AI 統合、ビジネスインテリジェンスツールの最新情報をお届けします。ぜひフォローしてください！

---

📜 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。

ライセンス全文は LICENSE ファイルに記載されています。

---