Metabase

Metabase MCP サーバー

Metabase には、AI クライアントが Metabase インスタンスに直接接続できるようにする、組み込みの Model Context Protocol (MCP) サーバーが含まれています。これは https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http を使用し、Metabase の Agent API を基盤として、検索、ナビゲーション、クエリ、可視化、コンテンツの作成/更新のためのツールを公開します。これらはすべて、接続するユーザーの権限にスコープされます。

エンドポイント

MCP サーバーは以下で利用可能です:

https://{your-metabase.example.com}/api/metabase-mcp

レガシーな /api/mcp パスは既存クライアントのエイリアスとして引き続き機能しますが、/api/metabase-mcp が公開すべき正規の URL です。

クライアントの接続

任意の MCP 互換クライアントを /api/metabase-mcp エンドポイントに向けます。例えば、Claude Code の場合:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Claude Desktop の場合は、同じ URL を使用して カスタムコネクタ を作成します。

Cursor の場合は、Settings > MCP を開き、タイプを streamable-http に設定し、URL を以下にして新しいサーバーを追加します:

https://{your-metabase.example.com}/api/metabase-mcp

認証

MCP クライアントは OAuth 2.0 経由で認証します。Metabase は独自の組み込み OAuth サーバーを実行するため、外部プロバイダーは不要です。

初回接続のフロー:

1. クライアントが Metabase の OAuth エンドポイントを検出します。
2. クライアントが自身を Metabase に登録します。
3. ユーザーは Metabase にリダイレクトされ、ログインして接続を承認します。
4. クライアントは、ユーザーの Metabase 権限にスコープされたアクセストークンを受け取ります。

ブラウザベースのセッション (Cookie 認証) もサポートされており、無制限のスコープを受け取ります。

スコープ

アクセストークンは、クライアントが使用できるツールを制限するためにスコープされます:

スコープ	アクセス権限
agent:search	search
agent:resource:read	read_resource (認証されたすべての呼び出し元に常に付与されます。URI ごとの権限チェックはディスパッチャー内で行われます)
agent:query:construct	construct_query
agent:query	query
agent:query:execute	execute_query
agent:sql:construct	construct_native_query
agent:sql:execute	execute_sql
agent:question:create	create_question
agent:question:update	update_question (「カードをコレクションに移動」とアーカイブも含みます)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (「メトリックをコレクションに移動」とアーカイブも含みます)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (アーカイブも含みます)
agent:collection:create	create_collection

ワイルドカードパターン (例: agent:*) は、そのプレフィックスを持つ任意のスコープに一致します。

OAuth 保護リソースメタデータは以下で利用可能です:

/.well-known/oauth-protected-resource/api/metabase-mcp

デフォルトでは、同意画面はカスタマイズの機会なしにすべてのスコープへのアクセスを許可します。

利用可能なツール

MCP サーバーは、Agent API エンドポイントメタデータから動的に生成される以下のツールを公開します:

検出 + 読み取り

ツール	説明
search	キーワードまたは自然言語クエリを使用して、テーブル、メトリック、カード、ダッシュボード、コレクションを検索します。
read_resource	metabase:// URI で 1 つ以上の Metabase エンティティを読み取ります。データベース/スキーマ/テーブル/コレクション/質問/ダッシュボード/メトリック/変換ナビゲーションをカバーします。呼び出しごとに最大 5 つの URI。

クエリ構築 + 実行

ツール	説明
construct_query	テーブルまたはメトリックに対するクエリを構築します。利用可能な場合、ユーザーの元の prompt を受け入れます。execute_query または visualize_query で使用するための不透明な query_handle を返します。
construct_native_query	データベースに対するネイティブ (生 SQL) クエリを構築します。create_question に渡して保存するための不透明な query_handle を返します。SQL は実行しません。ネイティブハンドルは execute_query/query によって拒否されます (生 SQL を実行するには execute_sql を使用してください)。
query	テーブルまたはメトリックに直接クエリを実行します。継続トークンによるページネーションをサポートします。
execute_query	以前に構築されたクエリを実行し、カラムメタデータ付きの結果を返します。
execute_sql	データベースに対して生の SQL クエリを実行します。ユーザーがターゲットデータベースに対するネイティブクエリ権限を持っている必要があります。mcp-execute-sql-enabled 設定によりインスタンス全体で無効にできます。
execute_question	ID で保存済みの質問を実行し、その行とカラムメタデータを返します。呼び出し元の権限で実行されます。パラメータ化された質問はサポートされていません (エラーを返します)。

書き込み

ツール	説明
create_metric	クエリを再利用可能なメトリックとして保存します。construct_query からの query_handle を受け入れます。クエリには 1 つの集計と最大 1 つの日付グループ化が必要です。
update_metric	保存済みメトリックを更新します。パッチセマンティクス。collection_id を設定すると移動します。archived: true を設定するとアーカイブします — 可逆的なソフトデリートで、メトリックの削除を求められたときに使用されます。置き換え用の query は有効なメトリックである必要があります。
create_question	クエリを名前付きの質問 (カード) として保存します。construct_query (MBQL) または construct_native_query (ネイティブ SQL) からの query_handle を受け入れます。ネイティブの保存にはネイティブクエリ DB 権限が必要です。
update_question	保存済みの質問を更新します。パッチセマンティクス。collection_id を設定するとカードを移動します。archived: true を設定するとアーカイブします — 可逆的なソフトデリートで、質問の削除を求められたときに使用されます。クエリの置き換えには construct_query または construct_native_query ハンドルを受け入れます。
create_dashboard	新しいダッシュボードを作成します。オプションで保存済みの質問を配置できます (グリッド上に自動配置)。
update_dashboard	ダッシュボードのメタデータ (名前、説明、コレクション、アーカイブ — 可逆的なソフトデリートで、ダッシュボードの削除を求められたときに使用されます) を更新します。
create_collection	新しいコレクションを作成します。オプションで parent_collection_id の下にネストできます。

クエリ結果はリクエストごとに 200 行に制限されています。より多くの行が利用可能な場合、レスポンスには次のページを取得するために渡すことができる continuation_token が含まれます。

read_resource リストのレスポンスは 25 アイテムに制限され、truncated / total シグナルが付きます。詳細を確認するには特定の URI にドリルダウンするか、search で絞り込みます。

リソース

サーバーは MCP リソース を公開するため、クライアントはツールの説明を肥大化させることなく、URI で補足コンテンツを取得できます。

リソース URI	説明
metabase://docs/construct-query.md	construct_query および query のプログラム構文: ソース、操作、演算子形式、実例、落とし穴。

read_resource ツール (上記) は、Metabase エンティティ (metabase://question/{id}、metabase://database/{id}/tables など) をナビゲートするために別の URI スキームを使用します。2 つの URI 名前空間は独立しています: metabase://docs/... は MCP resources/read 経由で取得される静的な参照コンテンツ用であり、metabase://table/... などは read_resource ツールに渡されるエンティティ URI です。

サポートされている JSON-RPC メソッド

メソッド	説明
initialize	MCP 接続を初期化します。サーバー機能とセッション ID を返します。
notifications/initialized	初期化が完了したことを示すクライアント通知。
tools/list	利用可能なツールを一覧表示します (トークンのスコープでフィルタリング)。
tools/call	引数を使用してツールを呼び出します。
resources/list	利用可能なリソースを一覧表示します (トークンのスコープでフィルタリング)。
resources/read	URI でリソースを読み取ります。初期化されたセッションが必要です。
ping	キープアライブ ping。

リクエストは個別に、または JSON-RPC バッチとして送信できます。サーバーは Accept ヘッダーに応じて JSON または SSE で応答します。

アーキテクチャ

実装は以下のファイルにあります:

• api.clj - HTTP ハンドラー。JSON-RPC リクエストを解析し、認証とセッションヘッダーを検証し、オリジンチェック (DNS リバインディング保護) を実施し、適切なメソッドにディスパッチします。JSON と SSE の両方のレスポンス形式をサポートします。

• tools.clj - ツールディスパッチとマニフェスト生成。Agent API エンドポイントメタデータからツールリストを構築し、スコープをチェックし、合成 Agent API リクエストを通じてツール呼び出しをルーティングします。

• resources.clj - MCP リソースレジストリとハンドラー。URI でキー付けされたドキュメントリソース (construct_query リファレンスなど) を保持し、resources/list および resources/read に対するスコープベースのアクセス制御を行います。

• scope.clj - スコープマッチングロジック。完全一致、ワイルドカードパターン、セッションベース認証のための ::unrestricted センチネルをサポートします。

リクエストフロー

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

参考資料

• MCPユーザードキュメント
• Agent APIソース
• Model Context Protocol仕様