Metabase MCP (headless)

@serdnaley/metabase-mcp

Metabase 向けのヘッドレス MCP サーバーです。 シンプルな API キーだけで、Metabase をあらゆる AI エージェント、アプリ、CI ジョブ、サーバーに接続できます。OAuth フローもブラウザーも、切り替えが必要な管理者設定もありません。

• ヘッドレス認証。 必要なのは Metabase API キー（またはメールアドレスとパスワード）だけです。インタラクティブな OAuth ログインが使えないサーバー、CI、コンテナー、独自のアプリやエージェントでも動作します。Metabase に組み込まれた MCP は OAuth のみと説明されており、0.60 以降では管理者による有効化が必要です。
• ローカルでもサービスとしても実行可能。 デスクトップクライアント向けの stdio、または共有環境やサーバーへのデプロイ向けのベアラートークン認証付き Streamable HTTP に対応しています。Metabase の認証情報はサーバー上に保持されます。
• 幅広い機能を網羅。 Metabase のクエリと操作に対応する 178 個のツールを備えています。ダッシュボード、質問、コレクション、ユーザー、グループ、権限、データベース、設定、アラート、トランスフォーム、エクスポートなどを扱えます。
• 必要なツールだけを利用可能。 ツールセットとツールごとの有効化・無効化により、モデルのコンテキストを小さく保てます。すべてのツールに読み取り専用／破壊的操作のヒントが付いているため、クライアントは読み取りを自動承認できます。
• あらゆる Metabase に対応。 Metabase OSS（無料版）と有料エディションで動作し、0.59 と 0.64 でテスト済みです。キャッシュ、モデルの永続化、モデレーションなどの有料限定機能は、インスタンスで利用可能な場合に動作します。CI では無料版を対象にテストしています。

Metabase 組み込みの MCP やその他の Metabase MCP サーバーとの比較については、docs/comparison.md をご覧ください。ツールの全カタログは serdnaley.github.io/metabase-mcp にあります。

機能

• 178 個の MCP ツール、33 個のツールセットに対応：検索、データベース、テーブル、コレクション、カード、ダッシュボード、アクション、データセット、ユーザー、グループ、権限、セグメント、リビジョン、設定、アラート、サブスクリプション、用語集、ドキュメント、タイムライン、ブックマーク、モデレーション、スニペット、X線分析、キャッシュ、永続化、アップロード、メトリクス、測定値、トランスフォーム、エクスポート、API キー、埋め込み、タスクとログ
• ツールセット：必要なものだけを読み込み（METABASE_TOOLSETS=query）、グロブを使って個別のツールを追加または除外できます
• ツールの注釈：すべてのツールに readOnlyHint / destructiveHint / idempotentHint を付与
• stdio または HTTP：共有環境へのデプロイ向けに、ベアラー認証付き Streamable HTTP に対応
• 読み取り専用モード：環境変数を 1 つ設定するだけで、すべての書き込みツールを非表示にできます
• 大規模な結果への安全対策：クエリ結果の簡潔化、行数とレスポンスサイズの上限、ページング
• リソースとプロンプト：データベース、カード、ダッシュボード、コレクションを閲覧できます。すぐに使えるワークフローも用意しています
• 管理作業の自動化：ユーザー、グループ、権限、設定、データベース接続、トランスフォーム
• 型安全：Metabase の OpenAPI 仕様から生成した HTTP クライアント
• 設定不要：npx で実行でき、インストールは不要です

インストール

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

claude mcp add metabase \
  --env METABASE_URL=https://your-metabase.example.com \
  --env METABASE_API_KEY=mb_xxx \
  -- npx -y @serdnaley/metabase-mcp

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

mcpServers:
  - name: metabase
    command: npx
    args:
      - "-y"
      - "@serdnaley/metabase-mcp"
    env:
      METABASE_URL: "https://your-metabase.example.com"
      METABASE_API_KEY: "mb_xxx"

{
  "context_servers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@serdnaley/metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxx"
      }
    }
  }
}

claude mcp add --transport http metabase https://mcp.example.com/mcp \
  --header "Authorization: Bearer $MCP_HTTP_TOKEN"

{
  "mcpServers": {
    "metabase": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_HTTP_TOKEN>" }
    }
  }
}

設定

*METABASE_API_KEY、またはMETABASE_EMAILとMETABASE_PASSWORDの両方を指定する必要があります。APIキーの使用を推奨します。

カスタムヘッダー

MetabaseがCloudflare Accessのサービストークンなど、独自のヘッダーを必要とするプロキシの背後にある場合は、METABASE_CUSTOM_HEADERSを使用します。JSONオブジェクトを指定します。

METABASE_CUSTOM_HEADERS='{"CF-Access-Client-Id": "xxx.access", "CF-Access-Client-Secret": "yyy"}'

または、改行または;で区切ったName: value形式のペアを指定します。

METABASE_CUSTOM_HEADERS='CF-Access-Client-Id: xxx.access; CF-Access-Client-Secret: yyy'

認証ヘッダー（X-API-Key、X-Metabase-Session）は、同じ名前のカスタムヘッダーより常に優先されます。不正な値が指定されている場合、サーバーは起動時に停止します。

ツールセット

各ツールのドメインはツールセット（dashboards、users、transforms などです。全リストはツールを参照してください）です。プリセットでまとめて選択できます。

METABASE_TOOLSETS=query,dashboards      # analyst assistant
METABASE_TOOLS_ENABLE=create_card       # plus one write tool
METABASE_TOOLS_DISABLE='delete_*'       # never delete anything

優先順位は、強い順に 読み取り専用モード > METABASE_TOOLS_DISABLE > METABASE_TOOLS_ENABLE > METABASE_TOOLSETS です。不明なツールセットがあると、起動時にサーバーが停止します。有効化／無効化パターンに一致するものがない場合は、警告がログに記録されます。起動ログ（stderr）には、有効なツールの数が表示されます。

大きな結果

クエリツール（execute_query、execute_card_query、run_metric）は、コンパクトな表示を返します。これにはcolumns（名前、型）とrowsが含まれ、Metabaseの列内部情報、results_metadata、インサイトは含まれません。生のレスポンスを取得するには、verbose: trueを指定してください。結果はMETABASE_MAX_ROWS行に制限され（呼び出しごとにmax_rowsを指定できますが、上限を超えることはできません）、offsetでページ分割されます。残りの結果を取得する方法はnoteに記載されます。各ツールのレスポンスはコンパクトなJSONで、METABASE_MAX_RESPONSE_CHARS文字に制限されます。SELECT * FROM ORDERSの10／100／500行の結果では、未整形のレスポンスと比べて94%／76%／60%小さくなります。結果セット全体を取得するには、output_pathを指定してエクスポートツールを使用してください。

リソースとプロンプト

ツールに加えて、サーバーは閲覧用のMCP リソース（コンパクトなJSON）として、metabase://databases、metabase://database/{id}/schema、metabase://card/{id}、metabase://dashboard/{id}、metabase://collection/{id}（ルートコレクションの場合はroot）を提供します。また、一般的なワークフロー用のプロンプトとして、explore-database、build-dashboard、explain-card、audit-permissionsを提供します。どちらもツールの選択設定に従います。リソースには対応するツールセットが必要で、プロンプトには使用するすべてのツールが必要です（そのため、読み取り専用モードではbuild-dashboardは表示されません）。

HTTP モード（共有／サーバーへのデプロイ）

METABASE_URL=https://metabase.example.com \
METABASE_API_KEY=mb_xxx \
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=3333 \
MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
npx -y @serdnaley/metabase-mcp

クライアントはAuthorization: Bearer <MCP_HTTP_TOKEN>を指定してhttp://<host>:3333/mcpに接続します。GET /healthは認証なしで応答し、情報は開示しません。このエンドポイントはステートレス（セッションなし）なので、水平方向にスケールできます。localhost以外で使用する場合は、TLS（リバースプロキシ）経由にしてください。トークンを持つ全員がMetabase APIキーのユーザーとして動作するため、対象者ごとに専用のキー、トークン、ツールセットを用意してください。

または、コンテナとして実行できます（ghcr.io/serdnaley/metabase-mcp、amd64 + arm64、デフォルトでHTTPモード）：

docker run -p 3333:3333 \
  -e METABASE_URL=https://metabase.example.com -e METABASE_API_KEY=mb_xxx \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  ghcr.io/serdnaley/metabase-mcp

Metabase API キーの取得

1. Metabaseインスタンスに移動します
2. 歯車アイコン > 管理者設定 > 認証 > APIキーをクリックします
3. 「APIキーを作成」をクリックします
4. 名前を付け、適切なグループ（例：管理者）を選択します
5. キーをコピーします。キーはmb_で始まります

使用例

「注文の傾向を示すダッシュボードを作成する」

AI アシスタントは次の操作を行います：

1. searchとget_database_metadataを使用してデータを確認します
2. create_cardを使用して質問を作成します（例：月別の注文数、製品別の売上）
3. create_dashboardを使用してダッシュボードを作成します
4. update_dashboard_cardsを使用して、レイアウトに合わせてカードを配置します

「第4四半期のレポートをすべてArchiveコレクションに移動する」

AI アシスタントは次の操作を行います：

1. searchを使用して第4四半期のレポートカードを探します
2. 必要に応じてcreate_collectionを使用してArchiveコレクションを作成します
3. 各カードでupdate_cardを使用して、新しいコレクションに移動します

「分析データベースにはどのようなテーブルがありますか？」

AI アシスタントは次の操作を行います：

1. list_databasesを使用してデータベースを探します
2. get_database_metadataを使用して、すべてのテーブル、フィールド、リレーションシップを一覧表示します

ツール

パラメーターを含む完全なカタログは、ツールカタログサイトを参照してください（コードから生成されています）。

Read tools (79, always available)

書き込みツール（99 個、読み取り専用モードでは非表示）

METABASE_TOOLSETS のプリセット：all（すべて）；query（search、databases、tables、dataset、cards、metrics、measures、segments、exports、activity、xrays）；content（search、collections、cards、dashboards、documents、snippets、timelines、bookmarks、glossary、revisions、moderation、notifications、exports）；admin（users、permissions、settings、databases、tables、cache、persistence、upload、transforms、actions、activity、eid-translation、api-keys、embedding、diagnostics）。

セキュリティ

読み取り専用モードでもexecute_queryを利用できます。 設定された Metabase アカウントがアクセスできる任意のデータベースに対して、任意の SQL を実行できます。Metabase は独自の権限モデルを適用しますが、このツールが追加の制限を設けることはありません。

書き込み操作を防ぐには、Metabase 自体で、Metabase API キーまたはアカウントに読み取り専用のデータベース権限が設定されていることを確認してください。

エクスポートではローカルファイルに書き込むことができます。 export_card_query、export_query、export_dashboard_pdfは読み取り専用モードでも利用でき（Metabase から読み取るだけです）、output_pathを指定すると、MCP サーバーを実行しているマシン上のその絶対パスに書き込みます。overwrite: trueを渡さない限り、既存のファイルを上書きすることはありません。Metabase はクエリの実行時と同じアクセスチェックをエクスポートにも適用します。独立した「結果のダウンロード」権限は Pro／Enterprise でのみ利用できます。

読み取り専用モードはセキュリティ境界ではありません。 METABASE_READ_ONLY_MODEは書き込みツールを非表示にするだけです。キーが実際にできることは Metabase で決まり、API キーには、そのグループの権限に加えてすべてのユーザーの権限が適用されます。読み取り専用のアシスタントには、キーをコレクションへの閲覧のみアクセス権を持つグループに設定し、「クエリの作成」をクエリビルダーのみ（またはなし）に設定したうえで、「すべてのユーザー」の権限もそれ以上に広がらないように制限してください。調査結果とセットアップのチェックリストについては、docs/read-only-and-permissions.mdを参照してください。

HTTP モードではベアラートークンが必要です。 MCP_TRANSPORT=httpは、ループバックホスト上でMCP_HTTP_ALLOW_NO_AUTH=trueが設定されている場合を除き、MCP_HTTP_TOKENがないと起動しません。トークンは一定時間で比較され、ループバックホストでは Host ヘッダーのチェックによって DNS リバインディングがブロックされます。このトークンには、設定された Metabase キーができることすべてを実行する権限があるため、そのキーと同様に取り扱い、localhost の外部では TLS 経由でエンドポイントを公開してください。

生 SQL はワンクリックで実行されます。 読み取りツールにはexecute_queryとexport_queryを含め、readOnlyHint: trueが設定されているため、クライアントが自動承認する場合があります。⚠️ SQL はそのまま送信されます。このサーバーはINSERT／UPDATE／DELETE／DDLをブロックせず、どちらのツールの説明にもその旨が記載されています。SQL による書き込みを防ぐ必要がある場合は、ネイティブクエリを実行できないグループの Metabase API キー（または読み取り専用権限を付与されたデータベースユーザー）を使用してください。docs/read-only-and-permissions.mdを参照してください。

アクションの種類は制限されています。 create_actionツールで許可されるアクションの種類は、queryとimplicitのみです。任意の外部リクエストを行う可能性がある HTTP アクションはブロックされます。

開発

bun install
bun run dev                    # Start the MCP server
bun run build                  # Build for npm
bun run generate-types         # Regenerate types from Metabase OpenAPI spec

テスト

テストは Docker 経由で実際の Metabase インスタンスに対して実行されます。

docker compose up -d             # Start Metabase (pinned version, see docker-compose.yml)
./tests/ci/wait-for-metabase.sh  # Wait for ready (~15s)
bun test                         # 276 tests
docker compose down              # Stop Metabase

Metabase v0.64.3.4（CI で固定されているバージョン）およびv0.59.6で検証済みです。別のリリースを試すには、次を実行してください。 MB_IMAGE=metabase/metabase:latest docker compose up -d。CI では、固定バージョンを更新する前に上流 API の変更を検知できるよう、週に一度、metabase:latestでもブロッキングなしのジョブとしてテストスイートを実行します。

アクション、トランスフォーム、CSV のアップロードは、docker-compose.ymlの Postgres「Test Warehouse」に対して実行されます。有料プランまたは不足しているサービスが必要な機能（モデレーション、キャッシュの無効化、モデルの永続化、またはウェアハウス自体）は、SKIP … (environment)というログ行を出して明示的にスキップされます。それ以外の API エラーが発生した場合、テストは失敗します。

仕組み

AI Client (Claude, Cursor, etc.)
  ↓ MCP protocol (stdio)
MCP Tool (zod schema + handler)
  ↓
Service function (business logic)
  ↓
openapi-fetch (type-safe HTTP client)
  ↓
Metabase REST API

このサーバーは Metabase のOpenAPI 仕様から TypeScript 型を生成し、型安全な API 呼び出しにopenapi-fetchを使用します。

ライセンス

MIT