metabase-mcp-server

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:

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

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

Related MCP server: Metabase MCP Server

Configuration

Tools

Discovery

Querying

Dashboards

Analysis & Export

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

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