metabase-mcp

MCP server for Metabase — gives AI agents full access to query, explore, and manage content in your Metabase instance.

Works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, etc.

Quick Start

npx metabase-mcp

That's it. No clone, no build. Just add it to your MCP config with the right env vars.

Configuration

Claude Code

Add to .mcp.json (project-level) or ~/.claude/settings.json (global):

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_...",
        "METABASE_DATABASE_ID": "2"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-mcp"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_...",
        "METABASE_DATABASE_ID": "2"
      }
    }
  }
}

Using a .env file

Instead of inline env vars, point to a .env file:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "metabase-mcp"],
      "env": {
        "METABASE_ENV_FILE": "/path/to/.env"
      }
    }
  }
}

Your .env file:

METABASE_URL=https://your-metabase.example.com
METABASE_API_KEY=mb_...
METABASE_DATABASE_ID=2

Environment Variables

| Variable | Required | Description | |---|---|---| | METABASE_URL | Yes | Metabase base URL (no trailing slash) | | METABASE_API_KEY | Yes | API key from Admin > Settings > Authentication > API Keys | | METABASE_DATABASE_ID | No | Default database ID for queries (default: 2) | | METABASE_ENV_FILE | No | Path to .env file to load config from |

Getting an API Key

1. Go to your Metabase instance
2. Navigate to Admin > Settings > Authentication > API Keys
3. Click Create API Key
4. Copy the key (starts with mb_)

Tools

Querying

| Tool | Description | |---|---| | query | Run raw SQL against any database. Returns CSV or JSON. | | export | Run SQL with no row limit — streams full results as CSV. | | run_card | Execute a saved question by ID. | | run_dashboard_card | Execute a specific card within a dashboard. |

Dashboards

| Tool | Description | |---|---| | list_dashboards | List all dashboards with id, name, description. | | get_dashboard | Get dashboard details including all its cards. | | create_dashboard | Create a new empty dashboard. | | add_card_to_dashboard | Add a saved question to a dashboard with position/size. |

Saved Questions (Cards)

| Tool | Description | |---|---| | list_cards | List all saved questions. | | get_card | Get card details including query definition. | | create_card | Create a new saved question from SQL. |

Schema & Exploration

| Tool | Description | |---|---| | list_databases | List all connected databases. | | list_tables | List tables in a database. | | get_table_schema | Get columns and types for a table. | | list_collections | List all collections. | | search | Full-text search across dashboards, cards, tables, collections. |

Examples

Once configured, just ask your AI agent naturally:

• "What tables are in the database?"
• "Run SELECT count() FROM users WHERE created_at > '2025-01-01'"*
• "Show me the schema for the orders table"
• "Create a dashboard called 'Weekly KPIs' and add the revenue card to it"
• "Search for anything related to churn"

Development

git clone https://github.com/your-org/metabase-mcp.git
cd metabase-mcp
npm install
npm run build

To use your local build instead of npx:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp/dist/server.js"],
      "env": { ... }
    }
  }
}

License

MIT