# Metabase MCP (headless)

> Metabase MCP (headless) is an open-source MCP server for browser automation. Headless Metabase MCP server using an API key, with 187 tools and read-only mode. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, self-hosted
- **Website:** https://serdnaley.github.io/metabase-mcp/
- **Repository:** https://github.com/serdnaley/metabase-mcp
- **MCP Registry name:** io.github.Serdnaley/metabase-mcp
- **Categories:** browser automation, analytics and data, databases
- **Listing updated:** 2026-11-14

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

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

- [Browser Use](https://ai-powered.com/mcp/browser-use): Browser Use is a freemium MCP server for browser automation.
- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [Oya Browser](https://ai-powered.com/mcp/oya-browser): Oya Browser is a freemium MCP server for browser automation.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Mantis](https://ai-powered.com/mcp/mantis-2): Mantis is an open-source MCP server for browser automation.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.

---
Source: https://ai-powered.com/mcp/metabase-mcp-headless
