Metabase MCP (headless)

@serdnaley/metabase-mcp

**专为 Metabase 打造的无头 MCP 服务。**只需普通的 API key，即可将 Metabase 接入任何 AI Agent、应用、CI 任务或服务器：无需 OAuth 流程、无需浏览器，也无需启用管理员开关。

• **无头身份验证。**只需 Metabase API key（或邮箱/密码）即可运行。它适用于无法交互式 OAuth 登录的场景：服务器、CI、容器、自有应用或 Agent。Metabase 内置的 MCP 文档说明其仅支持 OAuth，且需要管理员在 0.60+ 版本中启用。
• **可在本地运行，也可作为服务运行。**桌面客户端使用 stdio，共享部署和服务器部署则使用带 bearer token 的 Streamable HTTP。Metabase 凭据保留在服务器上。
• **全面覆盖。**提供 178 个工具，用于查询和操作 Metabase：仪表板、问题、集合、用户、群组、权限、数据库、设置、提醒、转换、导出等。
• **只启用所需工具。**通过工具集以及逐个工具启用/禁用功能，控制模型上下文大小。每个工具都带有只读/破坏性提示，因此客户端可以自动批准读取操作。
• **适用于任何 Metabase。**兼容 Metabase OSS（免费版）和付费版本，并已针对 0.59 和 0.64 进行测试。仅限付费版的功能（缓存、模型持久化、审核）可在实例支持时使用；CI 测试覆盖免费版。

与 Metabase 内置 MCP 及其他 Metabase MCP 服务的对比：docs/comparison.md。完整工具目录：serdnaley.github.io/metabase-mcp。

功能

• 178 个 MCP 工具，涵盖 33 个工具集：搜索、数据库、表、集合、卡片、仪表板、操作、数据集、用户、群组、权限、细分、修订、设置、提醒、订阅、术语表、文档、时间线、书签、审核、代码片段、X-ray、缓存、持久化、上传、指标、度量、转换、导出、API key、嵌入、任务与日志
• 工具集：仅加载所需内容（METABASE_TOOLSETS=query），还可通过 glob 模式添加或移除单个工具
• 工具注解：每个工具都带有 readOnlyHint / destructiveHint / idempotentHint
• stdio 或 HTTP：共享部署可使用带 bearer 身份验证的 Streamable HTTP
• 只读模式：通过一个环境变量隐藏所有写入工具
• 大结果安全保障：精简查询结果，限制行数和响应大小，并支持分页
• 资源与提示词：浏览数据库、卡片、仪表板和集合；提供现成工作流
• 管理自动化：用户、群组、权限、设置、数据库连接、转换
• 类型安全：HTTP 客户端由 Metabase 的 OpenAPI 规范生成
• 零配置：通过 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"}'

也可以使用以换行符或 ; 分隔的 名称: 值 对：

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 API 密钥或账号在 Metabase 中本身具有只读数据库权限。

导出可以写入本地文件。 export_card_query、export_query 和 export_dashboard_pdf 在只读模式下仍可用（它们只会从 Metabase 读取数据），并且在提供 output_path 时，会将文件写入运行 MCP 服务的机器上的该绝对路径。除非传入 overwrite: true，否则它们绝不会覆盖已有文件。Metabase 对导出执行的访问检查与运行查询时相同；单独的“下载结果”权限仅适用于 Pro/Enterprise。

只读模式不是安全边界。 METABASE_READ_ONLY_MODE 只会隐藏写入工具。密钥的实际权限由 Metabase 设置：API 密钥会获得其所属组以及 All Users 的权限。对于只读助手，请将密钥放入一个仅具有集合查看权限、且“创建查询”设为仅查询构建器（或不允许）的组中，并将 All Users 的权限限制在不超过该范围。请参阅 docs/read-only-and-permissions.md，了解探测结果和设置检查清单。

HTTP 模式需要 bearer token。 MCP_TRANSPORT=http 在未提供 MCP_HTTP_TOKEN 时会拒绝启动（以恒定时间进行比较）；但在环回主机上设置 MCP_HTTP_ALLOW_NO_AUTH=true 时例外，此时 Host 标头检查会阻止 DNS 重绑定。该令牌拥有配置的 Metabase 密钥所能执行的所有权限，因此请像保护该密钥一样保护它，并在 localhost 以外通过 TLS 提供端点服务。

原始 SQL 可一键执行。 只读工具均标记为 readOnlyHint: true，包括 execute_query 和 export_query，因此客户端可以自动批准它们。⚠️ 这些工具会原样发送 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 还会每周在 metabase:latest 上以非阻塞任务运行测试套件，因此上游 API 的变化会在固定版本升级前显现。

操作、转换和 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 类型，并使用 openapi-fetch 进行类型安全的 API 调用。

许可证

MIT