Metabase MCP (headless)

@serdnaley/metabase-mcp

[npm version] [License: MIT] [Tests] [Metabase] [MCP] [Glama score]

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.

• Headless auth. A Metabase API key (or email/password) is all it needs. That works where an interactive OAuth login can't: servers, CI, containers, your own app or agent. Metabase's built-in MCP is documented as OAuth-only and needs an admin to enable it on 0.60+.
• Runs locally or as a service. stdio for desktop clients, or Streamable HTTP with a bearer token for shared and server deployments. Metabase credentials stay on the server.
• Full coverage. 187 tools for querying and for running Metabase: dashboards, questions, collections, users, groups, permissions, databases, settings, alerts, transforms, exports and more.
• Only the tools you need. Toolsets and per-tool enable/disable keep the model's context small. Every tool carries read-only/destructive hints, so clients can auto-approve reads.
• Any Metabase. Works with Metabase OSS (free) and paid editions, tested against 0.59 and 0.64. Paid-only features (caching, model persistence, moderation) work when your instance has them; CI covers the free edition.

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.

Features

• 187 MCP tools across 34 toolsets: search, databases, tables, collections, cards, dashboards, actions, dataset, users, groups, permissions, segments, revisions, settings, alerts, subscriptions, glossary, documents, timelines, bookmarks, moderation, snippets, x-rays, cache, persistence, uploads, metrics, measures, transforms, exports, API keys, embedding, tasks & logs, explorations
• Toolsets: load only what you need (METABASE_TOOLSETS=query), add or drop single tools with globs
• Tool annotations: readOnlyHint / destructiveHint / idempotentHint on every tool
• stdio or HTTP: Streamable HTTP with bearer auth for shared deployments
• Read-only mode: hide every write tool with one env var
• Large-result safety: compact query results, row and response-size caps, paging
• Resources & prompts: browse databases, cards, dashboards and collections; ready-made workflows
• Admin automation: users, groups, permissions, settings, database connections, transforms
• Type-safe: HTTP client generated from Metabase's OpenAPI spec
• Zero config: runs via npx, no installation needed

Installation

{  "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>" }    }  }}

Configuration

*Either METABASE_API_KEY or both METABASE_EMAIL + METABASE_PASSWORD must be provided. API key is recommended.

Custom headers

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.

Toolsets

Each tool domain is a toolset (dashboards, users, transforms, ...; the full list is in Tools). Presets bundle them:

METABASE_TOOLSETS=query,dashboards      # analyst assistantMETABASE_TOOLS_ENABLE=create_card       # plus one write toolMETABASE_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.

Large results

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.

Resources and prompts

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).

HTTP mode (shared / server deployments)

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

Getting a Metabase API Key

1. Go to your Metabase instance
2. Click the gear icon > Admin settings > Authentication > API Keys
3. Click "Create API Key"
4. Give it a name and select the appropriate group (e.g., Administrators)
5. Copy the key — it starts with mb_

Examples

"Create a dashboard showing order trends"

The AI assistant will:

1. Use search and get_database_metadata to discover your data
2. Use create_card to create questions (e.g., orders by month, revenue by product)
3. Use create_dashboard to create the dashboard
4. Use update_dashboard_cards to arrange the cards with a layout

"Move all Q4 reports to the Archive collection"

The AI assistant will:

1. Use search to find Q4 report cards
2. Use create_collection to create an Archive collection if needed
3. Use update_card on each card to move it to the new collection

"What tables do we have in the analytics database?"

The AI assistant will:

1. Use list_databases to find the database
2. Use get_database_metadata to list all tables, fields, and relationships

Tools

Full catalog with parameters: see the tool catalog site (generated from the code).

Read tools (83, always available)

Write tools (104, hidden in read-only mode)

Presets for METABASE_TOOLSETS: all (everything); query (search, databases, tables, dataset, cards, metrics, measures, segments, exports, activity, xrays, explorations); 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).

Security

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.

Development

bun installbun run dev                    # Start the MCP serverbun run build                  # Build for npmbun run generate-types         # Regenerate types from Metabase OpenAPI spec

Testing

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 testsdocker compose down              # Stop Metabase

Verified against Metabase v0.65.2.6 (the CI pin; also v0.65.2.2–.5, v0.64.3.4–.6) 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.

How It Works

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.

License

MIT