Metabase MCP (headless)
Headless Metabase MCP server using an API key, with 187 tools and read-only mode
- 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-mcpAdd 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.comRequiredMETABASE_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 toolsMETABASE_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 winsMETABASE_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)

Browser Use
MCP serverBrowser agents and cloud browsers for AI, with an MCP server for web tasks
- 7 tools
- Remote
- Freemium
- 121K GitHub stars
- Browser automation

Scrapling MCP Server
MCP serverMCP 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

Agent-Native Analytics
MCP serverOpen-source analytics app where an AI agent builds charts and dashboards from your data
- Remote
- Open source
- 7.7K GitHub stars
- Analytics and data

Google Ads + Meta Ads + SEO/GEO MCP
MCP serverHosted 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

Oya Browser
MCP serverHIPAA-oriented agentic browser with replayable playbooks, reachable over MCP
- 32 tools
- Remote
- Freemium
- 349 GitHub stars
- Browser automation

Tapetide - Indian Stock Market MCP
MCP serverIndian NSE and BSE stock market data for AI assistants through 48 MCP tools
- 17 tools
- Remote
- Freemium
- 150 GitHub stars
- Finance and payments