Skip to content
MCP server

Metabase MCP (headless)

Headless Metabase MCP server using an API key, with 187 tools and read-only mode

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, API, self-hosted
Runs
Locally
Version
0.5.0
Listing updated
3 days ago

About Metabase MCP (headless)

Metabase MCP (headless) is an open-source MCP server for browser automation. It runs locally on your machine and is started by your AI client.

This server exists for the cases where Metabase's built-in MCP does not fit: the README says the built-in one is OAuth-only and needs an admin to enable it on Metabase 0.60 and later. Here a Metabase API key (or an email and password) is enough, so it can run in CI jobs, containers or your own agent without a browser login.

It exposes 187 tools (83 read, 104 write) across 34 toolsets, covering search, databases, tables and fields, collections, cards, dashboards, users, groups, permissions, settings, alerts, transforms and more. Every tool carries read-only, destructive and idempotent hints so a client can auto-approve reads. Environment variables trim what the model sees: METABASE_TOOLSETS picks groups, METABASE_TOOLS_ENABLE and METABASE_TOOLS_DISABLE take names or globs (disable always wins), and METABASE_READ_ONLY_MODE hides every write tool.

It runs over stdio through npx for desktop clients or as Streamable HTTP with a bearer token for shared deployments. It is tested against Metabase 0.59 and 0.64 and works with the free open-source edition as well as paid ones.

Install

Run in a terminal

claude mcp add metabase-mcp --env METABASE_URL='<METABASE_URL>' --env METABASE_API_KEY='<METABASE_API_KEY>' --env METABASE_PASSWORD='<METABASE_PASSWORD>' --env METABASE_CUSTOM_HEADERS='<METABASE_CUSTOM_HEADERS>' -- npx -y @serdnaley/metabase-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@serdnaley/metabase-mcp"
      ],
      "env": {
        "METABASE_URL": "<METABASE_URL>",
        "METABASE_API_KEY": "<METABASE_API_KEY>",
        "METABASE_PASSWORD": "<METABASE_PASSWORD>",
        "METABASE_CUSTOM_HEADERS": "<METABASE_CUSTOM_HEADERS>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@serdnaley/metabase-mcp"
      ],
      "env": {
        "METABASE_URL": "<METABASE_URL>",
        "METABASE_API_KEY": "<METABASE_API_KEY>",
        "METABASE_PASSWORD": "<METABASE_PASSWORD>",
        "METABASE_CUSTOM_HEADERS": "<METABASE_CUSTOM_HEADERS>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "metabase-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@serdnaley/metabase-mcp"
      ],
      "env": {
        "METABASE_URL": "<METABASE_URL>",
        "METABASE_API_KEY": "<METABASE_API_KEY>",
        "METABASE_PASSWORD": "<METABASE_PASSWORD>",
        "METABASE_CUSTOM_HEADERS": "<METABASE_CUSTOM_HEADERS>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@serdnaley/metabase-mcp"
      ],
      "env": {
        "METABASE_URL": "<METABASE_URL>",
        "METABASE_API_KEY": "<METABASE_API_KEY>",
        "METABASE_PASSWORD": "<METABASE_PASSWORD>",
        "METABASE_CUSTOM_HEADERS": "<METABASE_CUSTOM_HEADERS>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@serdnaley/metabase-mcp"
      ],
      "env": {
        "METABASE_URL": "<METABASE_URL>",
        "METABASE_API_KEY": "<METABASE_API_KEY>",
        "METABASE_PASSWORD": "<METABASE_PASSWORD>",
        "METABASE_CUSTOM_HEADERS": "<METABASE_CUSTOM_HEADERS>"
      }
    }
  }
}

Configuration

  • METABASE_URLMetabase base URL, e.g. https://metabase.example.comRequired
  • METABASE_API_KEYMetabase API key (or set METABASE_EMAIL + METABASE_PASSWORD)
  • METABASE_EMAILLogin email (alternative to an API key)
  • METABASE_PASSWORDLogin password (alternative to an API key)
  • METABASE_READ_ONLY_MODEtrue hides all write tools
  • METABASE_TOOLSETSComma list of toolsets or presets (all, query, content, admin)
  • METABASE_TOOLS_ENABLEExtra tools to enable (names or globs)
  • METABASE_TOOLS_DISABLETools to disable (names or globs); always wins
  • METABASE_CUSTOM_HEADERSExtra headers for every Metabase request (e.g. Cloudflare Access)

Tools this server provides (9)

Taken from the project documentation; the running server may differ.

search
Searches cards, dashboards, collections, tables and other Metabase entities.
list_databases
Lists the databases the user can access.
get_database_metadata
Returns tables, fields, types and relationships for a database.
create_database
Adds a new database connection.
sync_database_schema
Triggers a schema resync after DDL changes.
get_table
Returns table details and field info.
update_field
Updates a field's display name, semantic type, visibility or foreign-key target.
get_collection_tree
Returns the full collection hierarchy.
list_collections
Lists all collections.

What it does

API-key authentication
Connects with a Metabase API key or email and password, with no OAuth flow.
Toolsets and globs
Enable or disable groups or single tools to keep the model's context small.
Read-only mode
One environment variable hides all write tools.
Safety annotations
Each tool is marked read-only, destructive or idempotent.
Stdio or HTTP
Run locally through npx or serve Streamable HTTP with bearer auth.
Large-result limits
Compact query output with row and response-size caps and paging.

Good for

  • Let an agent in CI query Metabase without an interactive login
  • Audit or reorganise collections, dashboards and permissions through chat
  • Add or sync database connections from automation
  • Give analysts a read-only assistant over saved questions

Pricing

Open source

Free npm package; Metabase itself may be paid

Prices change. Check serdnaley.github.io before you buy.

Metabase MCP (headless) FAQ

How does it authenticate?

With METABASE_API_KEY, or METABASE_EMAIL plus METABASE_PASSWORD, against the URL in METABASE_URL.

Can I stop it making changes?

Yes. Set METABASE_READ_ONLY_MODE to true to hide every write tool.

Which Metabase editions work?

The README says open-source and paid editions, tested against 0.59 and 0.64; CI covers the free edition.

How do I install it in Claude Desktop?

Use the one-click .mcpb bundle from the latest release, or add an npx entry for @serdnaley/metabase-mcp to claude_desktop_config.json.

Is Metabase MCP (headless) free?

Yes. Metabase MCP (headless) is open source, so you can use and self-host it for free.

How do I add Metabase MCP (headless) to Claude Code?

Run this command in your terminal: claude mcp add metabase-mcp --env METABASE_URL='<METABASE_URL>' --env METABASE_API_KEY='<METABASE_API_KEY>' --env METABASE_PASSWORD='<METABASE_PASSWORD>' --env METABASE_CUSTOM_HEADERS='<METABASE_CUSTOM_HEADERS>' -- npx -y @serdnaley/metabase-mcp

What are the best alternatives to Metabase MCP (headless)?

The closest alternatives to Metabase MCP (headless) are Browser Use, Scrapling MCP Server, Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP and Oya Browser.

Alternatives to Metabase MCP (headless)

  1. Browser Use

    MCP server

    Browser agents and cloud browsers for AI, with an MCP server for web tasks

    • 7 tools
    • Remote
    • Freemium
    • 121K GitHub stars
    • Browser automation
  2. MCP server for AI clients to scrape sites with HTTP and stealth browser sessions

    Runs locally
    • 17 tools
    • Open source
    • 104K GitHub stars
    • Web search and scraping
  3. Open-source analytics app where an AI agent builds charts and dashboards from your data

    • Remote
    • Open source
    • 7.7K GitHub stars
    • Analytics and data
  4. Hosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat

    • 8 tools
    • Remote
    • Freemium
    • 8.1K GitHub stars
    • Marketing and SEO
  5. Oya Browser

    MCP server

    HIPAA-oriented agentic browser with replayable playbooks, reachable over MCP

    • 32 tools
    • Remote
    • Freemium
    • 349 GitHub stars
    • Browser automation
  6. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments