Metabase MCP (headless)

@serdnaley/metabase-mcp

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

Claude Desktop (one-click bundle)

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

Claude Desktop (JSON config)

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 Code (CLI)

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

Cursor

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.

Windsurf

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

Cline (VS Code)

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

Continue (VS Code)

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"

Zed

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

Remote / HTTP (any client that speaks Streamable HTTP)

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

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

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 t