Metabase

官方

官方 Metabase MCP 伺服器，用於搜尋資料、在語意層上建立查詢，並透過 MCP 客戶端視覺化結果。

GitHub

48.3k

你可以用 Metabase MCP 做什麼？

搜尋 Metabase 內容 — 使用關鍵字或自然語言查詢，透過 search 尋找資料表、指標、卡片、儀表板與集合。
導覽與檢查實體 — 透過 read_resource 搭配 metabase:// URI 讀取資料庫、結構描述、資料表、問題、儀表板與指標的中繼資料。
建立與執行查詢 — 使用 construct_query 針對資料表或指標建構查詢，再透過 execute_query 執行以取得結果與欄位中繼資料。
執行原始 SQL — 使用 execute_sql 對資料庫執行原生 SQL 查詢（需要原生查詢權限，且執行個體設定需啟用）。
儲存與更新問題 — 使用 create_question 和 update_question 從建構的查詢建立或修改已儲存的問題（卡片），包括移動或封存。
建立與管理儀表板 — 透過 create_dashboard 建立包含自動定位已儲存問題的新儀表板，並使用 update_dashboard 更新其中繼資料或封存。

文件

Metabase MCP 伺服器

Metabase 內建一個模型上下文協定 (MCP) 伺服器，讓 AI 用戶端可以直接連線到 Metabase 執行個體。它使用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 是應該公告的標準網址。

連線用戶端

將任何相容於 MCP 的用戶端指向 /api/metabase-mcp 端點。例如，使用 Claude Code：

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

對於 Claude Desktop，請使用相同的網址建立一個自訂連接器。

對於 Cursor，請開啟 設定 > MCP，並新增一個伺服器，類型設為 streamable-http，網址為：

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

驗證

MCP 用戶端透過 OAuth 2.0 進行驗證。Metabase 執行自己的嵌入式 OAuth 伺服器——不需要外部提供者。

首次連線的流程：

用戶端發現 Metabase 的 OAuth 端點。
用戶端向 Metabase 註冊自身。
使用者被重新導向至 Metabase 以登入並核准連線。
用戶端收到一個存取權杖，其範圍受限於該使用者的 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 讀取一個或多個 Metabase 實體。涵蓋資料庫/結構描述/表格/集合/問題/儀表板/指標/轉換導覽。每次呼叫最多 5 個 URI。

查詢建構與執行

工具	說明
`construct_query`	針對表格或指標建構查詢。當可用時，接受使用者的原始 `prompt`。傳回一個不透明的 `query_handle`，供 `execute_query` 或 `visualize_query` 使用。
`construct_native_query`	為資料庫建構原生（原始 SQL）查詢。傳回一個不透明的 `query_handle`，以提供給 `create_question` 並儲存它。不會執行 SQL；原生處理常式會被 `execute_query`/`query` 拒絕（請使用 `execute_sql` 來執行原始 SQL）。
`query`	直接查詢表格或指標。支援透過接續權杖進行分頁。
`execute_query`	執行先前建構的查詢，並傳回包含欄位中繼資料的結果。
`execute_sql`	針對資料庫執行原始 SQL 查詢。要求使用者在目標資料庫上擁有原生查詢權限。可以透過 `mcp-execute-sql-enabled` 設定在整個執行個體範圍內停用。
`execute_question`	透過 ID 執行已儲存的問題，並傳回其資料列和欄位中繼資料。在呼叫者的權限下執行。不支援參數化問題（會傳回錯誤）。

寫入

工具	說明
`create_metric`	將查詢儲存為可重複使用的指標。接受來自 `construct_query` 的 `query_handle`。查詢需要一個聚合和至多一個日期分組。
`update_metric`	更新已儲存的指標。修補語意。設定 `collection_id` 會移動它；設定 `archived: true` 會封存它——一個可逆的軟刪除，在要求刪除指標時使用。替換的 `query` 必須仍然是一個有效的指標。
`create_question`	將查詢儲存為一個具名問題（卡片）。接受來自 `construct_query`（MBQL）或 `construct_native_query`（原生 SQL）的 `query_handle`。儲存原生查詢需要原生查詢資料庫權限。
`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 工具（如上所述）使用獨立的 URI 方案來導覽 Metabase 實體（metabase://question/{id}、metabase://database/{id}/tables 等）。這兩個 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