接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @serdnaley/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add serdnaley-metabase-mcp -- npx -y @serdnaley/metabase-mcp@0.5.0在終端機中執行。
{ "mcpServers": { "serdnaley-metabase-mcp": { "command": "npx", "args": [ "-y", "@serdnaley/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
The headless MCP server for Metabase. Plug Metabase into any AI agent, app, CI job or server with a plain API key: no OAuth flow, no browser, no admin switch to flip.
How it compares with Metabase's built-in MCP and other Metabase MCP servers: docs/comparison.md. Full tool catalog: serdnaley.github.io/metabase-mcp.
METABASE_TOOLSETS=query), add or drop single tools with globsreadOnlyHint / destructiveHint / idempotentHint on every toolnpx, no installation neededDownload metabase-mcp-X.Y.Z.mcpb from the latest release and open it: Claude Desktop shows a form for the Metabase URL and API key. No Node.js setup or JSON editing.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Restart Claude Desktop after saving.
claude mcp add metabase \
--env METABASE_URL=https://your-metabase.example.com \
--env METABASE_API_KEY=mb_xxx \
-- npx -y @serdnaley/metabase-mcp
Or add to .claude/mcp.json:
{
"mcpServers": {
"metabase": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Restart Cursor after saving.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to your Cline MCP settings (accessible via the MCP Servers icon):
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Add to .continue/config.yaml:
mcpServers:
- name: metabase
command: npx
args:
- "-y"
- "@serdnaley/metabase-mcp"
env:
METABASE_URL: "https://your-metabase.example.com"
METABASE_API_KEY: "mb_xxx"
Add to your Zed settings.json:
{
"context_servers": {
"metabase": {
"command": "npx",
"args": ["-y", "@serdnaley/metabase-mcp"],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "mb_xxx"
}
}
}
}
Run the server once in HTTP mode (see HTTP mode), then point clients at it. Claude Code:
claude mcp add --transport http metabase https://mcp.example.com/mcp \
--header "Authorization: Bearer $MCP_HTTP_TOKEN"
Generic JSON config (Cursor, VS Code and others):
{
"mcpServers": {
"metabase": {
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer <MCP_HTTP_TOKEN>" }
}
}
}
*Either METABASE_API_KEY or both METABASE_EMAIL + METABASE_PASSWORD must be provided. API key is recommended.
Use METABASE_CUSTOM_HEADERS when Metabase sits behind a proxy that needs its own headers, such as Cloudflare Access service tokens. Give it a JSON object:
METABASE_CUSTOM_HEADERS='{"CF-Access-Client-Id": "xxx.access", "CF-Access-Client-Secret": "yyy"}'
or Name: value pairs separated by newlines or ;:
METABASE_CUSTOM_HEADERS='CF-Access-Client-Id: xxx.access; CF-Access-Client-Secret: yyy'
The auth headers (X-API-Key, X-Metabase-Session) always win over a custom header with the same name. A malformed value stops the server at startup.
Each tool domain is a toolset (dashboards, users, transforms, ...; the full list is in Tools). Presets bundle them:
METABASE_TOOLSETS=query,dashboards # analyst assistant
METABASE_TOOLS_ENABLE=create_card # plus one write tool
METABASE_TOOLS_DISABLE='delete_*' # never delete anything
Precedence, strongest first: read-only mode > METABASE_TOOLS_DISABLE > METABASE_TOOLS_ENABLE > METABASE_TOOLSETS. An unknown toolset stops the server at startup; an enable/disable pattern that matches nothing logs a warning. The startup log (stderr) shows how many tools are enabled.
Query tools (execute_query, execute_card_query, run_metric) return a compact view: columns
(name, type) and rows, without Metabase's column internals, results_metadata and insights. Pass
verbose: true for the raw response. Results are capped at METABASE_MAX_ROWS rows (per call:
max_rows, never above the cap) and paged with offset; a note says how to get the rest. Every tool
response is compact JSON capped at METABASE_MAX_RESPONSE_CHARS. For a 10 / 100 / 500-row
SELECT * FROM ORDERS this is 94% / 76% / 60% smaller than the raw pretty-printed response. For
full result sets use the export tools with output_path.
Besides tools the server offers MCP resources for browsing (compact JSON):
metabase://databases, metabase://database/{id}/schema, metabase://card/{id},
metabase://dashboard/{id}, metabase://collection/{id} (root for the root collection), and
prompts for common workflows: explore-database, build-dashboard, explain-card,
audit-permissions. Both follow the tool selection: a resource needs its toolset, a prompt needs
every tool it uses (so build-dashboard disappears in read-only mode).
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
Clients connect to http://<host>:3333/mcp with Authorization: Bearer <MCP_HTTP_TOKEN>. GET /health answers without auth and reveals nothing. The endpoint is stateless (no sessions), so it scales horizontally. Put it behind TLS (a reverse proxy) when it leaves localhost. Everyone with the token acts as the Metabase API key's user, so give each audience its own key, token and toolsets.
Or as a container (ghcr.io/serdnaley/metabase-mcp, amd64 + arm64, HTTP mode by default):
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
mb_The AI assistant will:
search and get_database_metadata to discover your datacreate_card to create questions (e.g., orders by month, revenue by product)create_dashboard to create the dashboardupdate_dashboard_cards to arrange the cards with a layoutThe AI assistant will:
search to find Q4 report cardscreate_collection to create an Archive collection if neededupdate_card on each card to move it to the new collectionThe AI assistant will:
list_databases to find the databaseget_database_metadata to list all tables, fields, and relationshipsFull catalog with parameters: see the tool catalog site (generated from the code).
Presets for METABASE_TOOLSETS: all (everything); 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 is available even in read-only mode. It can execute arbitrary SQL against any database the configured Metabase account has access to. Metabase enforces its own permission model, but this tool does not add additional restrictions.
To prevent write operations, ensure the Metabase API key or account has read-only database permissions within Metabase itself.
Exports can write local files. export_card_query, export_query and export_dashboard_pdf stay available in read-only mode (they only read from Metabase) and, when given output_path, write to that absolute path on the machine running the MCP server. They never overwrite an existing file unless overwrite: true is passed. Metabase applies the same access check to an export as to running the query; its separate "Download results" permission exists only on Pro/Enterprise.
Read-only mode is not a security boundary. METABASE_READ_ONLY_MODE only hides write tools. What a key can really do is set in Metabase: an API key gets the permissions of its group plus All Users. For a read-only assistant, put the key in a group with View-only collection access and "Create queries" set to query builder only (or no), and restrict All Users to no more than that. See docs/read-only-and-permissions.md for the probe results and a setup checklist.
HTTP mode requires a bearer token. MCP_TRANSPORT=http refuses to start without MCP_HTTP_TOKEN (compared in constant time), unless MCP_HTTP_ALLOW_NO_AUTH=true on a loopback host, where Host-header checks block DNS rebinding. The token grants everything the configured Metabase key can do, so treat it like that key and serve the endpoint over TLS outside localhost.
Raw SQL is one-click. Read tools are marked readOnlyHint: true, including execute_query and export_query, so clients can auto-approve them. ⚠️ Their SQL is sent as-is: this server does not block INSERT/UPDATE/DELETE/DDL, and both tool descriptions say so. Use a Metabase API key whose group cannot run native queries (or a database user with read-only grants) if SQL must not write — see docs/read-only-and-permissions.md.
Action types are restricted. The create_action tool only allows query and implicit action types. HTTP actions (which could make arbitrary outbound requests) are blocked.
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
Tests run against a real Metabase instance via Docker:
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
Verified against Metabase v0.64.3.6 (the CI pin; also v0.64.3.4–.5) and v0.59.6. To try another release:
MB_IMAGE=metabase/metabase:latest docker compose up -d. CI also runs the suite weekly on
metabase:latest as a non-blocking job, so upstream API drift shows up before the pin is bumped.
Actions, transforms and CSV uploads run against the Postgres "Test Warehouse" from
docker-compose.yml. Features that need a paid plan or a missing service (moderation, cache
invalidation, model persistence, or the warehouse itself) are skipped explicitly with a
SKIP … (environment) log line; any other API error fails the test.
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
The server generates TypeScript types from Metabase's OpenAPI spec and uses openapi-fetch for type-safe API calls.
MIT
Headless MCP server for Metabase: API-key auth (no OAuth), stdio or HTTP, 178 tools with toolsets, works on every Metabase tier
{ "mcpServers": { "serdnaley-metabase-mcp": { "command": "npx", "args": [ "-y", "@serdnaley/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
@serdnaley/metabase 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 Headless MCP server for Metabase: API-key auth (no OAuth), stdio or HTTP, 178 tools with toolsets, works on every Metabase tier