Skip to main content
Glama
metabase-mcp

metabase-mcp

by voducdan

Metabase MCP Server - Connect AI Assistants to Your Metabase Analytics

PyPI version Python 3.12+ License: MIT FastMCP

A high-performance Model Context Protocol (MCP) server for Metabase, enabling AI assistants like Claude, Cursor, and other MCP clients to interact seamlessly with your Metabase instance. Query databases, execute SQL, manage dashboards, and automate analytics workflows with natural language through AI-powered database operations.

Perfect for: Data analysts, developers, and teams looking to integrate AI assistants with their Metabase business intelligence platform for automated SQL queries, dashboard management, and data exploration.

Key Features

Database Operations

  • List Databases: Browse all configured Metabase databases

  • Table Discovery: Explore tables with metadata and descriptions

  • Field Inspection: Get detailed field/column information with smart pagination

Query & Analytics

  • SQL Execution: Run native SQL queries with parameter support and templating

  • MongoDB Support: Execute native MongoDB queries with automatic JSON conversion for aggregation pipelines

  • Card Management: Execute, create, and manage Metabase questions/cards (SQL and MongoDB)

  • Collection Organization: Create and manage collections for better organization

  • Natural Language Queries: Let AI assistants translate questions into SQL or MongoDB queries

Authentication & Security

  • API Key Support: Secure authentication via Metabase API keys (recommended)

  • Session-based Auth: Alternative email/password authentication

  • Environment Variables: Secure credential management via .env files

AI Assistant Integration

  • Claude Desktop: Native integration with Anthropic's Claude AI

  • Cursor IDE: Seamless integration for AI-assisted development

  • Any MCP Client: Compatible with all Model Context Protocol clients

Enhanced Performance & Reliability

  • Context-aware Logging: Real-time logging with debug, info, warning, and error levels visible to AI clients

  • Proper Error Handling: FastMCP ToolError exceptions for better error messages and debugging

  • Middleware Stack: Built-in error handling and logging middleware for production reliability

  • Best Practices: Follows latest FastMCP patterns with duplicate prevention and clean configuration

  • Modern Python: Uses Python 3.12+ type hints (| syntax) for better type safety

Related MCP server: Metabase MCP Server

Quick Start

Prerequisites

  • Python 3.12+

  • Metabase instance with API access

  • uvx or uv package manager

Installation

Option 1: Using uvx (Easiest - No Installation Required)

# Run directly without installing (like npx for Python)
uvx metabase-mcp

# With environment variables
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

Option 2: Install from PyPI

# Install globally
uv tool install metabase-mcp

# Or with pip
pip install metabase-mcp

# Then run
metabase-mcp

Option 3: Development Setup (From Source)

# Clone the repository
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp

# Install dependencies
uv sync

# Run the server
uv run python server.py

Configuration

Create a .env file with your Metabase credentials:

cp .env.example .env

Configuration Options

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

Option 2: Email/Password Authentication

METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-password

Optional: Metabase API HTTP Timeout

METABASE_HTTP_TIMEOUT=30.0  # Default: 30.0 seconds

Optional: Custom Host/Port for SSE/HTTP

HOST=localhost  # Default: 0.0.0.0
PORT=9000      # Default: 8000

Usage

Run the Server

Quick Start (No Setup Required)

# Run directly with uvx
uvx metabase-mcp

# With custom Metabase instance
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

From Source (Development)

# STDIO transport (default)
uv run python server.py

# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --sse

# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --http

# Custom host and port via environment variables
HOST=localhost PORT=9000 uv run python server.py --sse
HOST=192.168.1.100 PORT=8080 uv run python server.py --http

Cursor Integration

You can manually configure Cursor by editing your Cursor settings.

For SSE transport: You must start the server before using Cursor:

uv run python server.py --sse

Claude Desktop Integration

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uvx",
            "args": ["metabase-mcp"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Option 2: Using Local Installation

If you've cloned the repository:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/absolute/path/to/metabase-mcp",
                "python",
                "server.py"
            ],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Option 3: Using FastMCP CLI

fastmcp install server.py -n "Metabase MCP"

Available Tools

Database Operations

Tool

Description

list_databases

List all configured databases in Metabase

list_tables

Get all tables in a specific database with metadata

get_table_fields

Retrieve field/column information for a table

Query Operations

Tool

Description

execute_query

Execute native SQL queries with parameter support

execute_mongodb_query

Execute native MongoDB queries with automatic JSON conversion for aggregation pipelines

execute_card

Run saved Metabase questions/cards

Card Management

Tool

Description

list_cards

List all saved questions/cards

create_card

Create new questions/cards with SQL queries

create_mongodb_card

Create new MongoDB questions/cards with native query support

Collection Management

Tool

Description

list_collections

Browse all collections

create_collection

Create new collections for organization

Transport Methods

The server supports multiple transport methods:

  • STDIO (default): For IDE integration (Cursor, Claude Desktop)

  • SSE: Server-Sent Events for web applications

  • HTTP: Standard HTTP for API access

uv run python server.py                        # STDIO (default)
uv run python server.py --sse                  # SSE (HOST=0.0.0.0, PORT=8000)
uv run python server.py --http                 # HTTP (HOST=0.0.0.0, PORT=8000)
HOST=localhost PORT=9000 uv run python server.py --sse   # Custom host/port

Development

Setup Development Environment

# Install with dev dependencies
uv sync --group dev

# Or with pip
pip install -r requirements-dev.txt

Code Quality

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy server.py

Usage Examples

Query Examples

# List all databases
databases = await list_databases()

# Execute a SQL query
result = await execute_query(
    database_id=1,
    query="SELECT * FROM users LIMIT 10"
)

# Create and run a card
card = await create_card(
    name="Active Users Report",
    database_id=1,
    query="SELECT COUNT(*) FROM users WHERE active = true",
    collection_id=2
)

Project Structure

metabase-mcp/
├── server.py                 # Main MCP server implementation
├── pyproject.toml           # Project configuration and dependencies
└── .env.example             # Environment variables template

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Resources

Keywords & Topics

metabase mcp model-context-protocol claude cursor ai-assistant fastmcp sql database analytics business-intelligence bi data-analysis anthropic llm python automation api data-science query-builder natural-language-sql

Star History

If you find this project useful, please consider giving it a star! It helps others discover this tool.

Use Cases

  • Natural Language Database Queries: Ask Claude to query your Metabase databases using plain English

  • Automated Report Generation: Use AI to create and manage Metabase cards and collections

  • Data Exploration: Let AI assistants help you discover insights from your data

  • SQL Query Assistance: Get help writing and optimizing SQL queries through AI

  • Dashboard Management: Automate the creation and organization of Metabase dashboards

  • Data Analysis Workflows: Integrate AI-powered analytics into your development workflow

Available Tools

28 tools
add_card_to_dashboardA

Add an existing card to a dashboard at a specified position and size.

Args: dashboard_id: The ID of the dashboard to add the card to. card_id: The ID of the card to add. col: Column position on the dashboard grid (default: 0). row: Row position on the dashboard grid (default: 0). size_x: Width of the card in grid units (default: 6). size_y: Height of the card in grid units (default: 4).

Returns: The created dashboard card object.

Inputs: dashboard_id (required), card_id (required), col, row, +2 more. Returns: object

create_cardA

Create a new question/card in Metabase.

Args: name: Name of the card. database_id: ID of the database to query. query: SQL query for the card. description: Optional description. collection_id: Optional collection to place the card in. visualization_settings: Optional visualization configuration.

Returns: The created card object.

Inputs: name (required), database_id (required), query (required), description, +2 more. Returns: object

create_collectionB

Create a new collection in Metabase.

Args: name: Name of the collection. description: Optional description. color: Optional color for the collection. parent_id: Optional parent collection ID.

Returns: The created collection object.

Inputs: name (required), description, color, parent_id. Returns: object

create_dashboardA
Create a new dashboard in Metabase.

Args:
    name: Name of the dashboard.
    description: Optional description of the dashboard.
    collection_id: Optional collection ID to place the dashboard in.
    parameters: Optional list of parameter/filter configurations for the dashboard.

– Returns: The created dashboard object.

Inputs: name (required), description, collection_id, parameters. Returns: object

create_modelA

Create a new model in Metabase.

A model is a special type of saved question that acts as a curated dataset. Models can define metadata for their columns and serve as building blocks for other questions.

Args: name: Name of the model. database_id: ID of the database to query. query: SQL query that defines the model. description: Optional description of the model. collection_id: Optional collection to place the model in. result_metadata: Optional list of column metadata dicts. Each dict can include keys like "name", "display_name", "base_type", "semantic_type", "description", and "field_ref". visualization_settings: Optional visualization configuration.

Returns: The created model object.

Inputs: name (required), database_id (required), query (required), description, +3 more. Returns: object

create_mongodb_cardA

Create a new MongoDB question/card in Metabase.

Args: name: Name of the card. database_id: ID of the MongoDB database. collection: MongoDB collection name. query: MongoDB query string (aggregation pipeline or query). description: Optional description. collection_id: Optional collection to place the card in. visualization_settings: Optional visualization configuration.

Returns: The created MongoDB card object.

Inputs: name (required), database_id (required), collection (required), query (required), +3 more. Returns: object

execute_cardB

Execute a saved Metabase question/card and retrieve results.

Args: card_id: The ID of the card to execute. parameters: Optional parameters for the card execution.

Returns: Card execution results.

Inputs: card_id (required), parameters. Returns: object

execute_mongodb_queryA

Execute a MongoDB native query against a Metabase database.

Args: database_id: The ID of the MongoDB database to query. collection: The MongoDB collection name. query: The MongoDB query (aggregation pipeline array or query object). native_parameters: Optional parameters for the query.

Returns: Query execution results.

Inputs: database_id (required), collection (required), query (required), native_parameters. Returns: object

execute_queryA

Execute a native SQL query against a Metabase database.

Args: database_id: The ID of the database to query. query: The SQL query to execute. native_parameters: Optional parameters for the query.

Returns: Query execution results.

Inputs: database_id (required), query (required), native_parameters. Returns: object

get_dashboard_cardsB

Get the cards and their layout information for a specific dashboard.

Returns each card's id, name, display type, size, and position on the dashboard grid (col, row, size_x, size_y).

Args: dashboard_id: The ID of the dashboard.

Returns: A list of dashboard card objects with layout and card metadata.

Inputs: dashboard_id (required). Returns: result

get_table_fieldsA

Get all fields/columns in a specific table.

Args: table_id: The ID of the table. limit: Maximum number of fields to return (default: 20).

Returns: Dictionary with field metadata, truncated if necessary.

Inputs: table_id (required), limit. Returns: object

list_cardsA

List all saved questions/cards in Metabase.

Returns: Dictionary containing all cards with their metadata.

Inputs: no named parameters. Returns: object

list_collectionsA

List all collections in Metabase that the current user has read permissions for.

Args: archived: If true, return only archived collections. exclude_other_user_collections: If true, hide other users' personal collections. namespace: Filter collections by namespace (e.g. "snippets" for snippet folders). personal_only: If true, return only personal collections (where personal_owner_id is not null).

Returns: Dictionary containing all collections with their metadata.

Inputs: archived, exclude_other_user_collections, namespace, personal_only. Returns: object

list_dashboardsA

List all dashboards in Metabase.

Returns: A list of dashboards with their metadata including id, name, description, collection_id, and creator info.

Inputs: no named parameters. Returns: result

list_dashboard_tab_cardsA

List the cards belonging to a specific tab on a dashboard.

Args: dashboard_id: The ID of the dashboard. tab_id: The ID of the tab (from list_dashboard_tabs).

Returns: A list of dashcards on the given tab with layout and card metadata.

Inputs: dashboard_id (required), tab_id (required). Returns: result

list_dashboard_tabsA

List all tabs configured on a dashboard.

Args: dashboard_id: The ID of the dashboard.

Returns: A list of tab objects with id, name, and position. Empty list if the dashboard has no tabs.

Inputs: dashboard_id (required). Returns: result

list_databasesA

List all databases configured in Metabase.

Returns: A dictionary containing all available databases with their metadata.

Inputs: no named parameters. Returns: object

list_tablesA

List all tables in a specific database.

Args: database_id: The ID of the database to query.

Returns: Formatted markdown table showing table details.

Inputs: database_id (required). Returns: result

reposition_dashboard_cardsA

Reposition and/or resize multiple cards on a dashboard in a single update.

Use this to rearrange a dashboard layout atomically. Any dashcards not included in positions keep their current layout.

Args: dashboard_id: The ID of the dashboard. positions: A list of layout updates. Each entry must include dashcard_id and may include any of col, row, size_x, size_y. Omitted fields on an entry keep their current values.

Returns: The updated dashboard object.

Inputs: dashboard_id (required), positions (required). Returns: object

set_card_template_tagsA

Set or update the template tags on a card's native SQL query.

Metabase auto-creates template tags for each {{variable}} in SQL, but they default to type "text". Use this tool to change a tag's type (e.g. to "date" or "number"), set a display name, default value, required flag, or convert to a field filter ("dimension").

Each entry in template_tags is keyed by tag name and may include:

  • type: "text" | "number" | "date" | "dimension" | "card" | "snippet"

  • display-name: human-readable label

  • default: default value

  • required: bool

  • dimension: [field-id, ] # only for type "dimension"

  • widget-type: e.g. "date/single", "date/range", "category" # for dimension

Existing fields (including the auto-generated id UUID and name) are preserved when merge=True.

Args: card_id: The ID of the card whose native query tags should be updated. template_tags: Map of tag-name -> tag-config. merge: If True (default), merge with existing tags. If False, replace entirely.

Returns: The updated card object.

Inputs: card_id (required), template_tags (required), merge. Returns: object

set_dashcard_inline_parametersA

Attach dashboard filters inline to specific dashcards.

By default, dashboard parameters render as filter widgets at the top of the dashboard. Setting inline_parameters on a dashcard moves those filter widgets to appear attached to that specific card instead of the header.

Each entry in inline_parameters must include:

  • dashcard_id: the dashcard to target (from get_dashboard_cards)

  • parameter_ids: list of dashboard parameter ids (strings) to render inline on this dashcard. The parameters must already exist on the dashboard (see update_dashboard).

Existing inline_parameters on each touched dashcard are preserved and extended, unless replace=True (in which case the list on each touched dashcard is fully replaced by the ids provided here). Dashcards not referenced in inline_parameters are left untouched.

Note: the dashboard parameter should still be mapped to the card's template tag via set_dashcard_parameter_mappings — inline placement only affects where the widget renders, not how values are wired into the card's query.

Args: dashboard_id: The ID of the dashboard. inline_parameters: List of entries as described above. replace: If True, replace inline_parameters on touched dashcards instead of appending.

Returns: The updated dashboard object.

Inputs: dashboard_id (required), inline_parameters (required), replace. Returns: object

set_dashcard_parameter_mappingsA

Wire dashboard parameters to card template tags on specific dashcards.

Each mapping entry must include:

  • dashcard_id: the dashcard to target (from get_dashboard_cards)

  • parameter_id: the dashboard parameter's id (set via update_dashboard)

  • template_tag: the tag name used in the card's SQL (e.g. "start_date")

Optional per-entry fields:

  • kind: "variable" (default) for plain {{tag}} vars, or "dimension" for field-filter tags. Produces the correct target shape.

  • card_id: overrides the dashcard's own card_id in the mapping (rare — needed for series cards).

  • target: raw Metabase target array; if provided, used verbatim and overrides kind/template_tag.

Existing parameter_mappings on each touched dashcard are preserved and extended, unless replace=True (in which case the mappings for each touched dashcard are fully replaced by the entries provided here). Dashcards not referenced in mappings are left untouched.

Args: dashboard_id: The ID of the dashboard. mappings: List of mapping entries as described above. replace: If True, replace parameter_mappings on touched dashcards instead of appending.

Returns: The updated dashboard object.

Inputs: dashboard_id (required), mappings (required), replace. Returns: object

update_cardA

Update properties of a saved question/card in Metabase.

When query is updated, existing template-tags on the card are preserved by default (re-sent alongside the new SQL) so filters wired to the card aren't silently wiped. Pass template_tags to set/replace them atomically with the SQL update.

Args: card_id: The ID of the card to update. name: New name for the card. description: New description for the card. query: New SQL query for the card. database_id: New database ID (required if changing query). display: Display type (e.g. "table", "bar", "line", "pie", "scalar", "row", "area", "combo", "pivot", "smartscalar", "funnel", "waterfall", "map"). collection_id: Move the card to a different collection. visualization_settings: Visualization settings to apply. archived: Set to true to archive the card, false to unarchive. template_tags: Replacement template-tags map (tag-name -> config). If provided, replaces the card's template-tags. If omitted while query is set, existing template-tags are preserved unchanged.

Returns: The updated card object.

Inputs: card_id (required), name, description, query, +6 more. Returns: object

update_card_displayA

Update the display type of a saved question/card in Metabase.

Args: card_id: The ID of the card to update. display: The display type (e.g. "table", "bar", "line", "pie", "scalar", "row", "area", "combo", "pivot", "smartscalar", "funnel", "waterfall", "map"). visualization_settings: Optional visualization settings to apply with the display change.

Returns: The updated card object.

Inputs: card_id (required), display (required), visualization_settings. Returns: object

update_card_parametersA

Set the card-level parameters list on a saved question.

Card parameters drive the filter widgets shown on a card's own page AND are what Metabase uses to wire dashboard parameters into the card. For a date filter to render as a date picker (instead of a plain text box), the card must have a matching parameter entry — the template-tag type alone is not enough.

Each parameter is a dict. Common keys:

  • id: the template-tag's UUID (must match dataset_query.native.template-tags[name].id)

  • name: display name, e.g. "Start date"

  • slug: URL slug, e.g. "start_date"

  • type: widget type, e.g. "date/single", "date/range", "date/all-options", "category", "string/=", "number/="

  • target: link back to the template tag, e.g. ["variable", ["template-tag", "start_date"]] (for text/number/date vars) ["dimension", ["template-tag", "start_date"]] (for field filters)

  • default: default value (optional)

  • values_source_type / values_source_config: dropdown data source (optional)

  • values_query_type: "list" | "search" | "none" (optional)

Args: card_id: The ID of the card whose parameters should be updated. parameters: List of parameter configs. When merge=False (default) this replaces the card's entire parameters list. When merge=True, entries are matched by id (or by slug if id is missing) and merged into existing parameters; new entries are appended.

Returns: The updated card object.

Inputs: card_id (required), parameters (required), merge. Returns: object

update_dashboardA

Update properties of a dashboard, including its parameter/filter list.

Use parameters to define dashboard-level filters. Each parameter is a dict with keys like id (string, required — a stable identifier), name, slug, type (e.g. "date/all-options", "date/single", "date/range", "category", "string/=", "number/="), and optional default, sectionId, values_source_type, values_source_config.

Args: dashboard_id: The ID of the dashboard to update. name: New name for the dashboard. description: New description for the dashboard. collection_id: Move the dashboard to a different collection. parameters: Full replacement list of dashboard parameters. archived: Set true to archive, false to unarchive.

Returns: The updated dashboard object.

Inputs: dashboard_id (required), name, description, collection_id, +2 more. Returns: object

update_dashboard_card_positionA

Reposition or resize a single card on a dashboard.

Only the provided fields are updated; omitted fields keep their current values.

Args: dashboard_id: The ID of the dashboard. dashcard_id: The ID of the dashcard (from get_dashboard_cards) to move or resize. col: New column position on the dashboard grid. row: New row position on the dashboard grid. size_x: New width in grid units. size_y: New height in grid units.

Returns: The updated dashboard object.

Inputs: dashboard_id (required), dashcard_id (required), col, row, +2 more. Returns: object

update_modelA

Update an existing model in Metabase.

Args: card_id: The ID of the model to update. name: New name for the model. description: New description for the model. query: New SQL query for the model. database_id: New database ID (required if changing query). collection_id: Move the model to a different collection. result_metadata: Updated column metadata list. Each dict can include keys like "name", "display_name", "base_type", "semantic_type", "description", and "field_ref". visualization_settings: Visualization settings to apply. archived: Set to true to archive the model, false to unarchive.

Returns: The updated model object.

Inputs: card_id (required), name, description, query, +5 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 28 tools

    Disambiguation3/5

    Many tools have distinct purposes, but there is overlap between similar tools like create_card vs create_model, update_card vs update_card_display vs update_card_parameters, and reposition_dashboard_cards vs update_dashboard_card_position, which could cause confusion.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun snake_case pattern, but there are exceptions like get_dashboard_cards (uses get instead of list), set_dashcard_inline_parameters (set instead of update), and inconsistent use of 'set' vs 'update' across tools.

    Tool Count3/5

    28 tools is on the high side for a Metabase MCP server. While it covers many features, some tools feel redundant (e.g., multiple dashboard layout tools) and could be consolidated.

    Completeness2/5

    The tool set covers core CRUD for cards and dashboards, but lacks delete operations for cards, dashboards, collections, and models. Missing get single card/dashboard endpoints. This creates dead ends for common workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Metabase analytics platform, allowing them to query databases, manage dashboards and cards, execute SQL queries, and access analytics data through natural language.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Metabase analytics platform, allowing them to query databases, manage dashboards, execute SQL queries, and organize collections through natural language.
      167 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Metabase analytics platform, allowing users to query databases, manage dashboards and cards, execute SQL queries, and access analytics data through natural language.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Metabase analytics platform, allowing them to query databases, execute SQL, manage dashboards and cards, and access analytics data through natural language.
      -