Metabase

官方

官方Metabase MCP服务器，用于通过MCP客户端搜索数据、在语义层构建查询以及可视化结果。

GitHub

48.3k

你可以用 Metabase MCP 做什么？

搜索 Metabase 内容 — 使用 search 通过关键词或自然语言查询查找表、指标、卡片、仪表盘和集合。
导航与检查实体 — 通过 metabase:// URI 使用 read_resource 读取数据库、模式、表、问题、仪表盘和指标的元数据。
构建并运行查询 — 使用 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 是应对外公布的规范 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，请打开 设置 > MCP，然后添加一个新服务器，类型设置为 streamable-http，URL 为：

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