metabase-mcp-server

<h1 align="center">Metabase MCP Server</h1>

<p align="center"> Connect any AI agent to your Metabase instance.<br/> Read-only tools · MBQL + native SQL · cross-DB analysis · data export </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"/></a> <img src="https://img.shields.io/badge/Node.js-18%2B-green.svg" alt="Node 18+"/> <img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP Compatible"/> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> · <a href="#tools">Tools</a> · <a href="#configuration">Configuration</a> · <a href="#examples">Examples</a> · <a href="#troubleshooting">Troubleshooting</a> </p>

---

An MCP server that gives AI agents read-only access to any Metabase instance. Explore schemas, query databases, run saved questions, compare data across databases, and export results — all through natural conversation.

Works with Claude Code, Cursor, and any MCP-compatible client.

Quick Start

git clone https://github.com/arkanji/metabase-mcp-server.git
cd metabase-mcp-server
npm install && npm run build

Then add it to your AI client:

<details> <summary><strong>Claude Code</strong> — <code>.mcp.json</code></summary>

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxx"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code></summary>

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxx"
      }
    }
  }
}

</details>

Configuration

Variable	Required	Default	Description
METABASE_URL	Yes	—	Your Metabase instance URL. Do not include /api.
METABASE_API_KEY	Yes	—	How to generate one — go to Admin > Settings > API Keys.
METABASE_EXPORT_DIR	No	~/Downloads/	Where export_dataset writes CSV/JSON files.

Tools

Discovery

Tool	What it does
list_databases	List all connected databases
list_tables	List tables in a database
get_table_fields	Get column names, IDs, and types for a table
preview_table	Sample rows to understand data shape
search	Find saved questions, dashboards, or tables by keyword

Querying

Tool	What it does
query_dataset	Run structured MBQL queries (aggregations, filters, breakouts)
run_native_query	Run raw SQL queries (requires SQL permission on API key)
run_saved_question	Execute an existing saved question by ID
get_card_metadata	Inspect a saved question's definition without running it
list_saved_questions	List all saved questions, optionally by database

Dashboards

Tool	What it does
list_dashboards	List all dashboards
get_dashboard	Get a dashboard's cards and layout details

Analysis & Export

Tool	What it does
cross_db_overlap	Find overlapping values across two databases (e.g. shared emails between CRM and marketing)
export_dataset	Export up to 500K rows to CSV/JSON with auto-pagination

Examples

"How many orders did we get last month?"

The agent will:

1. list_databases → find your orders database
2. list_tables → find the orders table
3. get_table_fields → get the date and status field IDs
4. query_dataset → run a count aggregation with a date filter

"Export all active customers to a CSV"

The agent will:

1. Discover the table and field IDs
2. export_dataset → auto-paginates through the 2,000-row Metabase cap, writes to ~/Downloads/

"Which customers exist in both our CRM and marketing databases?"

The agent will:

1. Identify the email field in both databases
2. cross_db_overlap → fetches both sides, computes the intersection in memory

How It Works

You ──→ AI Agent ──→ MCP Server ──→ Metabase REST API ──→ Your Databases
         (Claude,      (this       (x-api-key auth,
          Cursor)       project)    read-only)

Key things to know:

• Read-only — no write operations. Native SQL queries are validated to reject INSERT, UPDATE, DELETE, DROP, etc.
• 2,000-row cap — Metabase limits query results to 2,000 rows. Use aggregations for analytics, or export_dataset for full data extraction (auto-paginates up to 500K rows).
• 30s timeout — each API request times out after 30 seconds to prevent hung connections.
• MBQL — Metabase's structured query language. Columns are referenced by field ID (not name), so always call get_table_fields first to look them up.

Security

• API keys are passed via environment variables and sent as x-api-key headers. They are never logged or exposed in tool responses.
• Write-operation guard — run_native_query rejects queries that start with write keywords (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE). This is a basic prefix check, not a comprehensive SQL parser — Metabase's own permission system is the primary access control.
• No secrets in code — the server reads credentials only from env vars at startup.

Troubleshooting

Problem	Cause	Fix
METABASE_URL environment variable is required	Missing env var	Set METABASE_URL in your .mcp.json env block or shell
Metabase API error 401	Invalid or expired API key	Generate a new key in Metabase Admin > Settings > API Keys
Metabase API error 403	Key lacks permission for this action	Check your key's permission group in Metabase. Native SQL requires explicit "native query" permission.
Metabase API returned empty response	URL is wrong or Metabase is down	Verify METABASE_URL points to your instance (no trailing /api)
Write operations are not allowed	SQL query starts with INSERT/UPDATE/etc.	This server is read-only. Use SELECT queries only.
Queries return empty results	Wrong field IDs or filters	Call get_table_fields to verify field IDs, then preview_table to check data shape
Export hangs	Very large dataset + slow Metabase	Add filters to reduce row count. Exports are capped at 500K rows.

Development

npm run dev      # Watch mode — recompiles on save
npm run build    # One-time build
npm start        # Run the server

Should work with any Metabase version that supports the /api/dataset endpoint and API key authentication (generally v0.44+).

Contributing

Issues and PRs are welcome. Please open an issue first to discuss significant changes.

License

MIT

---

<p align="center"> Built by <a href="https://github.com/arkanji">Arkanji</a> </p>