@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. 178 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
- 178 MCP tools across 33 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
- Toolsets: load only what you need (
METABASE_TOOLSETS=query), add or drop single tools with globs - Tool annotations:
readOnlyHint/destructiveHint/idempotentHinton 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
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.
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>" }
}
}
}
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 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
- Go to your Metabase instance
- Click the gear icon > Admin settings > Authentication > API Keys
- Click "Create API Key"
- Give it a name and select the appropriate group (e.g., Administrators)
- Copy the key — it starts with
mb_
Examples
"Create a dashboard showing order trends"
The AI assistant will:
- Use
searchandget_database_metadatato discover your data - Use
create_cardto create questions (e.g., orders by month, revenue by product) - Use
create_dashboardto create the dashboard - Use
update_dashboard_cardsto arrange the cards with a layout
"Move all Q4 reports to the Archive collection"
The AI assistant will:
- Use
searchto find Q4 report cards - Use
create_collectionto create an Archive collection if needed - Use
update_cardon each card to move it to the new collection
"What tables do we have in the analytics database?"
The AI assistant will:
- Use
list_databasesto find the database - Use
get_database_metadatato list all tables, fields, and relationships
Tools
Full catalog with parameters: see the tool catalog site (generated from the code).
Read tools (79, always available)
Write tools (99, hidden in read-only mode)
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).
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 install
bun run dev # Start the MCP server
bun run build # Build for npm
bun 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 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.
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
