metabase-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@metabase-mcp run a SQL query to get monthly sales for 2024"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Metabase MCP Server - Connect AI Assistants to Your Metabase Analytics
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
.envfiles
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
ToolErrorexceptions for better error messages and debuggingMiddleware 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
uvxoruvpackage 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-mcpOption 2: Install from PyPI
# Install globally
uv tool install metabase-mcp
# Or with pip
pip install metabase-mcp
# Then run
metabase-mcpOption 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.pyConfiguration
Create a .env file with your Metabase credentials:
cp .env.example .envConfiguration Options
Option 1: API Key Authentication (Recommended)
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-hereOption 2: Email/Password Authentication
METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-passwordOptional: Metabase API HTTP Timeout
METABASE_HTTP_TIMEOUT=30.0 # Default: 30.0 secondsOptional: Custom Host/Port for SSE/HTTP
HOST=localhost # Default: 0.0.0.0
PORT=9000 # Default: 8000Usage
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-mcpFrom 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 --httpCursor 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 --sseClaude Desktop Integration
Option 1: Using uvx (Recommended)
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 all configured databases in Metabase |
| Get all tables in a specific database with metadata |
| Retrieve field/column information for a table |
Query Operations
Tool | Description |
| Execute native SQL queries with parameter support |
| Execute native MongoDB queries with automatic JSON conversion for aggregation pipelines |
| Run saved Metabase questions/cards |
Card Management
Tool | Description |
| List all saved questions/cards |
| Create new questions/cards with SQL queries |
| Create new MongoDB questions/cards with native query support |
Collection Management
Tool | Description |
| Browse all collections |
| 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/portDevelopment
Setup Development Environment
# Install with dev dependencies
uv sync --group dev
# Or with pip
pip install -r requirements-dev.txtCode Quality
# Run linting
uv run ruff check .
# Format code
uv run ruff format .
# Type checking
uv run mypy server.pyUsage 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 templateContributing
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 toolsadd_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 correcttargetshape.card_id: overrides the dashcard's own card_id in the mapping (rare — needed for series cards).
target: raw Metabase
targetarray; if provided, used verbatim and overrideskind/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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Work with your database from AI tools: ask, export, approved changes, and scheduled jobs.
Connect AI assistants to Preset to explore data, charts, and dashboards in authorized workspaces.
Query and update Teable records, manage tables, and access the Teable API with AI agents.
Query your Logspot analytics, companies, and revenue from any AI assistant, and run your actions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-