# metabase-ai-assistant [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/enessari/metabase-ai-assistant  
**GitHub Stars:** 49  
**npm Downloads (last month):** 203  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/metabase-ai-assistant

## Description
MCP Server for Metabase - 111 tools for SQL generation, dashboards & PostgreSQL

## Tools
Capabilities this server exposes over MCP:

- **db_list** — Get list of all databases in Metabase instance with IDs and connection types
- **db_test_speed** — Check database response time and performance - run this before heavy operations to determine optimal timeout settings
- **db_schemas** — Get all schema names in specified database - useful for data exploration and finding business data locations
- **db_tables** — Get comprehensive table list across all schemas with field counts - provides overview of data structure
- **db_table_profile** — Get comprehensive table profile: row count, column types, distinct values, sample data. Auto-detects dimension/reference tables (dim_, ref_, lookup_ prefix). Ideal for understanding lookup tables before writing queries.
- **sql_execute** — Run SQL queries against database - supports SELECT, DDL with security controls, returns formatted results. For long-running queries (>60s), use sql_submit instead.
- **sql_submit** — Submit a long-running SQL query asynchronously. Returns immediately with job_id. Use sql_status to check progress. Ideal for queries that may take minutes.
- **sql_status** — Check status of an async query submitted via sql_submit. Returns results when complete.
- **sql_cancel** — Cancel a running async query. Also attempts to cancel on database server.
- **mb_question_create** — Create new question/chart
- **mb_questions** — Browse saved questions and charts in Metabase - filter by collection to find specific reports
- **mb_dashboard_create** — Create a new dashboard in Metabase with layout options
- **mb_dashboard_template_executive** — Create an executive dashboard with standard KPIs, metrics, and layout - auto-generates questions and arranges them professionally
- **mb_dashboards** — List existing dashboards
- **mb_question_create_parametric** — Create a parametric question with filters, variables, and dynamic queries - supports date ranges, dropdowns, and field filters
- **mb_dashboard_add_card** — Add a question card to a dashboard with specific positioning, sizing, and layout
- **mb_dashboard_add_card_sql** — Add multiple cards to a dashboard using direct SQL inserts. Bypasses API limits, ensures precise positioning, and prevents timeouts. Use this for complex layouts.
- **mb_dashboard_update_layout** — Batch update position and size of multiple dashboard cards via direct SQL. Guarantees layout application.
- **mb_create_parametric_question** — Create a native SQL question with parameters (variables) directly via SQL. Essential for creating cards that accept dashboard filters.
- **mb_link_dashboard_filter** — Link a dashboard filter to a card parameter via SQL. Updates parameter_mappings.
- **web_fetch_metabase_docs** — Fetch specific Metabase documentation page for API details, best practices, and feature information
- **web_explore_metabase_docs** — Comprehensively explore Metabase documentation - crawls main docs and discovers all available sections, APIs, and guides
- **web_search_metabase_docs** — Search across all Metabase documentation for specific topics, APIs, or solutions - uses intelligent content analysis
- **meta_find_internal_db** — Auto-detect the Metabase Internal Application Database ID from connected databases. Required for advanced metadata tools.
- **meta_audit_logs** — Analyze query performance and usage history from internal logs. Finds slow queries and top users.
- **meta_lineage** — Find dependencies: Which dashboards and questions use a specific table or field? (Impact Analysis)
- **meta_advanced_search** — Deep search within SQL code, visualization settings, and descriptions across all questions and dashboards.
- **web_metabase_api_reference** — Get comprehensive Metabase API reference with endpoints, parameters, examples, and response formats
- **mb_metric_create** — Create a custom metric definition in Metabase for KPI tracking and business intelligence
- **mb_dashboard_add_filter** — Add a filter to a dashboard for interactive data filtering across multiple cards
- **mb_dashboard_layout_optimize** — Automatically optimize dashboard layout for better visual hierarchy and user experience
- **mb_auto_describe** — Automatically generate AI-powered descriptions for databases, tables, and fields with timestamp signatures
- **ai_sql_generate** — Convert natural language requests into SQL queries - understands business context and table relationships
- **ai_sql_optimize** — Analyze and improve SQL query performance - suggests indexes, query restructuring, and execution optimizations
- **ai_sql_explain** — Break down complex SQL queries into plain English - explains joins, aggregations, and business logic
- **db_connection_info** — Get database connection information from Metabase (requires admin permissions)
- **db_table_create** — Create new table directly in database with security controls - requires schema selection and approval
- **db_view_create** — Create a new view directly in the database (with claude_ai_ prefix)
- **db_matview_create** — Create a new materialized view directly in the database (PostgreSQL only)
- **db_index_create** — Create database index for query performance - improves search and join operations on specified columns
- **db_table_ddl** — Get the DDL (CREATE statement) for a table
- **db_view_ddl** — Get the DDL (CREATE statement) for a view
- **db_ai_list** — List all database objects created by AI (with claude_ai_ prefix)
- **db_ai_drop** — Safely remove AI-created database objects - only works on objects with claude_ai_ prefix for security
- **db_schema_explore** — Fast schema exploration with table counts and basic info - lightweight method for discovering data structure
- **db_test_speed** — Quick test to check database connection and response time
- **db_schema_analyze** — Deep schema analysis with column details, keys, constraints - requires direct DB connection for comprehensive insights
- **db_relationships_detect** — Detect existing foreign key relationships between tables - finds explicitly defined database constraints
- **ai_relationships_suggest** — AI-powered virtual relationship discovery using naming patterns and data analysis - finds implicit connections between tables
- **mb_relationships_create** — Create virtual relationships in Metabase model - enables cross-table queries and improved dashboard capabilities
- **activity_log_init** — Initialize activity logging system for a database - creates log table and starts tracking operations
- **activity_session_summary** — Get comprehensive summary of current or specified session activities and performance
- **activity_operation_stats** — Analyze operation statistics and patterns over specified time period
- **activity_database_usage** — Get database usage patterns and statistics showing which databases are most active
- **activity_error_analysis** — Analyze error patterns and common failure points to identify improvement opportunities
- **activity_performance_insights** — Get performance insights showing slow operations and optimization opportunities
- **activity_timeline** — Get chronological timeline of recent activities for debugging and monitoring
- **activity_cleanup** — Clean up old activity logs to maintain performance and storage efficiency
- **definition_tables_init** — Initialize definition lookup tables system for documentation, metrics, templates, and search
- **definition_search_terms** — Search business terms and definitions with relevance ranking
- **definition_get_metric** — Get metric definition with calculation formula and business context
- **definition_get_template** — Get dashboard or question template with layout and configuration
- **definition_global_search** — Search across all definition tables with unified results
- **parametric_question_create** — Create parametric question with date, text search, and category filters
- **parametric_dashboard_create** — Create dashboard with parametric questions and shared filters
- **parametric_template_preset** — Create parametric question from preset templates (date range analysis, category filter, text search, period comparison)
- **db_vacuum_analyze** — Run VACUUM and ANALYZE on PostgreSQL tables to optimize storage and update statistics (PostgreSQL only)
- **db_query_explain** — Get execution plan for a SQL query - shows how PostgreSQL will execute the query
- **db_table_stats** — Get table statistics including row count, size, dead tuples, last vacuum/analyze times
- **db_index_usage** — Analyze index usage statistics - find unused or rarely used indexes
- **mb_visualization_settings** — Get or update visualization settings for a question (chart type, colors, labels, etc.)
- **mb_visualization_recommend** — AI-powered visualization recommendation based on query results and data types
- **mb_collection_create** — Create a new collection in Metabase for organizing questions and dashboards
- **mb_collection_list** — List all collections with hierarchy and item counts
- **mb_collection_move** — Move questions, dashboards, or collections to a different collection
- **mb_action_create** — Create a Metabase Action for data modification (INSERT, UPDATE, DELETE)
- **mb_action_list** — List all actions for a model
- **mb_action_execute** — Execute a Metabase action with parameters
- **mb_alert_create** — Create an alert for a question that triggers on specified conditions
- **mb_alert_list** — List all alerts, optionally filtered by question
- **mb_pulse_create** — Create a scheduled report (pulse) that sends dashboards/questions on a schedule
- **mb_field_metadata** — Get or update field metadata including display name, description, and semantic type
- **mb_table_metadata** — Get or update table metadata including display name, description, and visibility
- **mb_field_values** — Get distinct values for a field (for filter dropdowns)
- **mb_embed_url_generate** — Generate signed embedding URL for a dashboard or question
- **mb_embed_settings** — Get embedding settings and enabled features for the Metabase instance
- **mb_user_list** — List all Metabase users with filtering options
- **mb_user_get** — Get detailed information about a specific user
- **mb_user_create** — Create a new Metabase user
- **mb_user_update** — Update an existing user
- **mb_user_disable** — Disable (deactivate) a user account
- **mb_permission_group_list** — List all permission groups in Metabase
- **mb_permission_group_create** — Create a new permission group
- **mb_permission_group_delete** — Delete a permission group
- **mb_permission_group_add_user** — Add a user to a permission group
- **mb_permission_group_remove_user** — Remove a user from a permission group
- **mb_collection_permissions_get** — Get permissions graph for a collection
- **mb_collection_permissions_update** — Update permissions for a collection
- **mb_card_get** — Get detailed information about a specific card/question
- **mb_card_update** — Update an existing card/question
- **mb_card_delete** — Permanently delete a card/question
- **mb_card_archive** — Archive a card/question (soft delete)
- **mb_card_data** — Execute a card/question and get the results in specified format
- **mb_dashboard_get** — Get detailed information about a dashboard
- **mb_dashboard_update** — Update dashboard properties
- **mb_dashboard_delete** — Delete a dashboard
- **mb_dashboard_card_update** — Update card position and size on a dashboard
- **mb_dashboard_card_remove** — Remove a card from a dashboard
- **mb_card_copy** — Copy a card/question to a new location
- **mb_card_clone** — Clone a card and retarget to a different table (for template cards)
- **mb_dashboard_copy** — Copy a dashboard with all its cards
- **mb_collection_copy** — Copy an entire collection with all contents
- **mb_search** — Search across all Metabase items (cards, dashboards, collections, tables)
- **mb_segment_create** — Create a segment (reusable filter) for a table
- **mb_segment_list** — List all segments
- **mb_bookmark_create** — Bookmark an item for quick access
- **mb_bookmark_list** — List all bookmarked items
- **mb_bookmark_delete** — Remove a bookmark
- **db_sync_schema** — Trigger schema sync for a database
- **mb_cache_invalidate** — Invalidate cache for specific items or entire database
- **mb_meta_query_performance** — Get comprehensive query performance statistics from Metabase metadata - analyze execution times, cache hit rates, error rates, and identify slow queries. Requires MB_METADATA_ENABLED=true.
- **mb_meta_content_usage** — Analyze content usage patterns - find popular questions/dashboards, unused content, orphaned cards. Great for content cleanup and optimization. Requires MB_METADATA_ENABLED=true.
- **mb_meta_user_activity** — Get user activity statistics - active users, inactive users, query patterns, login history. Useful for license optimization and user engagement analysis. Requires MB_METADATA_ENABLED=true.
- **mb_meta_database_usage** — Analyze database usage patterns - query counts, performance, errors by database and table. Requires MB_METADATA_ENABLED=true.
- **mb_meta_dashboard_complexity** — Analyze dashboard complexity - card counts, load times, performance issues. Identify dashboards that need optimization. Requires MB_METADATA_ENABLED=true.
- **mb_meta_info** — Get overview of Metabase metadata database - active users, questions, dashboards, recent activity. Quick health check. Requires MB_METADATA_ENABLED=true.
- **mb_meta_table_dependencies** — Analyze table dependencies - find all questions and dashboards that depend on a specific table. Essential for impact analysis before schema changes. Requires MB_METADATA_ENABLED=true.
- **mb_meta_impact_analysis** — Analyze impact of removing a table - breaking changes, affected questions/dashboards, severity assessment, and recommendations. Critical for safe database migrations. Requires MB_METADATA_ENABLED=true.
- **mb_meta_optimization_recommendations** — Get comprehensive optimization recommendations - index suggestions, materialized view candidates, and cache optimization. Data-driven performance improvements. Requires MB_METADATA_ENABLED=true.
- **mb_meta_error_patterns** — Analyze error patterns and categorize recurring errors - identify systemic issues, suggest resolutions, find questions with high error rates. Proactive error management. Requires MB_METADATA_ENABLED=true.
- **mb_meta_export_workspace** — 📤 Export workspace to JSON (questions, dashboards, collections). READ-ONLY operation - safe to execute. Perfect for backups and migrations. Requires MB_METADATA_ENABLED=true.
- **mb_meta_import_preview** — 🔍 Preview import impact WITHOUT making changes (dry-run). Analyzes conflicts, detects issues, provides recommendations. ALWAYS run this before actual import. Requires MB_METADATA_ENABLED=true.
- **mb_meta_compare_environments** — 🔄 Compare current environment with another (dev → staging → prod). Identifies drift, missing items, and differences. READ-ONLY operation. Requires MB_METADATA_ENABLED=true.
- **mb_meta_auto_cleanup** — 🧹 Auto-cleanup unused content with SAFETY CHECKS. ⚠️ DRY-RUN by default, requires approved:true for execution. Finds unused questions (180+ days), orphaned cards, empty collections, broken questions. Requires MB_METADATA_ENABLED=true.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "metabase-ai-assistant": {
    "command": "npx",
    "args": ["-y","metabase-ai-assistant"],
    "env": {
      "METABASE_URL": "",
      "METABASE_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `METABASE_URL`, `METABASE_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What metabase-ai-assistant MCP server does

The metabase-ai-assistant MCP server exposes Metabase operations to language models, coding assistants, and automated workflows through MCP. Its tools cover SQL generation and execution, database introspection, dashboard construction, query analysis, anomaly detection, and index recommendations. It also includes workflows for working with dbt metadata, MetricFlow semantic models, lineage, and governed business rules.

The project supports Metabase Open Source and Enterprise deployments and documents compatibility from Metabase 0.43 through current 0.61+ releases. It can detect or work across different Metabase API and query formats, including session-token and API-key authentication paths.

## How it works

The metabase-ai-assistant MCP server runs as a Node.js process and communicates with an MCP client over the configured transport. A client sends tool calls, and the server uses the Metabase API and related local metadata inputs to perform the requested operation.

The SQL workflow includes `ai_sql_execute_and_heal`, which can retry a failed query through an automated recovery loop. Documented recovery cases include syntax errors, misspelled columns, missing grouping clauses, and dialect differences across PostgreSQL, MySQL, BigQuery, Snowflake, and SQLite. Fix history is retained in a healing trail.

For dbt-oriented work, tools can inspect manifests and semantic models, prioritize sources, resolve multi-hop lineage, advise on pre-aggregations, build dashboards from YAML metadata, and export approved semantic definitions to YAML. Semantic memory operations use proposal, approval, deprecation, restoration, and listing stages rather than silently changing or deleting rules.

## Setup and configuration

Install with NPX:

```bash
npx metabase-ai-assistant
```

Alternatively, install the package globally with npm. Configure the MCP client to launch the command and provide these environment variables:

- `METABASE_URL`: URL of the Metabase deployment.
- `METABASE_API_KEY`: API key used to authenticate with Metabase.
- `METABASE_READ_ONLY_MODE`: optional setting shown in the example client configuration for restricting operations.

The README provides configurations for Claude Desktop, Cursor, Windsurf, and VS Code. It also documents an SSE/HTTP mode that exposes an OpenAPI document for ChatGPT Actions, plus deployment instructions for Cloudflare Workers.

## Tools and capabilities

The metabase-ai-assistant MCP server includes tools and workflows for:

- Generating, executing, and repairing SQL.
- Inspecting databases, models, and Metabase metadata.
- Creating and arranging dashboards from structured definitions.
- Detecting anomalies and advising on query indexes.
- Scanning dbt projects and inspecting MetricFlow models.
- Resolving lineage and suggesting pre-aggregation designs.
- Proposing, approving, deprecating, restoring, and listing semantic rules.
- Masking emails, phone numbers, national identifiers, payment-card numbers, IP addresses, and tokens in output.

## Limitations and notes

The documentation presents different tool totals in different sections, including 143, 152, and the repository listing’s 111. Treat the exact count as version-dependent or unresolved rather than relying on one figure. Read-only mode is shown as a client configuration option, but write-capable operations remain available unless that setting is used. Database dialect behavior and Metabase features may vary by deployment version and configuration.

_Full upstream README: https://allmcps.com/mcp/metabase-ai-assistant/readme_