Metabase AI Assistant is an enterprise-grade Model Context Protocol (MCP) server that connects Large Language Models (LLMs), AI coding assistants, and automated data workflows directly to your Metabase Business Intelligence instance.
Featuring 143 dedicated tools, native dbt Semantic Layer awareness, Governance-First Business Memory (explicit approvals, soft-deprecation), autonomous self-healing SQL execution, full-scale dashboard architecting, proactive anomaly detection, query index advisory, zero-leak PII masking, and strict security guardrails.
- 🇬🇧 English (Main Documentation)
- 🇹🇷 Türkçe Dokümantasyon
- 🇨🇳 中文文档 (Chinese)
- 🇸🇦 التوثيق باللغة العربية (Arabic)
- Core Architectural Highlights
- Next-Gen Autonomous Features (v5.1)
- Metabase Version Compatibility
- Quick Start & Installation
- Client Configuration & Desktop Setup
- Tool Categories Overview (143 Tools)
- Testing & Quality Assurance
- Project Roadmap & Upcoming Features
- License
Metabase AI Assistant transforms standard AI interfaces (Claude Desktop, Cursor, VS Code, ChatGPT, Gemini, automated agent frameworks) into full-fledged Metabase power users:
- dbt Semantic Layer & Model Tier Awareness: Prioritizes curated Gold Marts (
fct_,dim_,rpt_) over raw staging tables to ensure clean, tested metric calculations. - Governance-First Semantic Memory Engine: Learns company-specific business rules with explicit proposal and approval workflows. Implements safe soft-deprecation (no hard deletes) with mandatory audit comments.
- Autonomous Self-Healing SQL Engine: Executes queries, catches database syntax/schema errors, inspects table structures, repairs queries automatically across 3 retry loops, and returns audited results.
- End-to-End Autonomous Dashboard Architect: Generates 6–8 tailored metric cards, calculates collision-free 24-column grid coordinates, saves questions, builds dashboards, and binds global filters in a single request.
- AI Query Index & Materialized View Advisor: Analyzes SQL and
EXPLAINquery plans to recommend optimal composite indexes and materialized view definitions. - Proactive KPI Anomaly & Outlier Detector: Multi-model statistical engine (Z-Score, Tukey IQR, Bollinger Bands) to detect metric anomalies with dimensional root-cause hypotheses.
- Zero-Leak Enterprise PII Masker: Real-time masking of emails, phone numbers, national IDs, credit cards, IP addresses, and tokens before data leaves for LLM contexts.
dbt_inspect_models: Parses dbtmanifest.jsonand MetricFlow semantic models.dbt_prioritize_sources: Dynamically routes natural language questions to pre-aggregated, tested dimensional and fact tables.
semantic_memory_propose: Proposes a business rule inPENDING_APPROVALstatus.semantic_memory_approve: Explicitly activates the rule with required data steward comments.semantic_memory_deprecate: Safely soft-archives rules with mandatory audit reasons (DEPRECATED).semantic_memory_restore: Instantly restores archived rules.semantic_memory_list: Lists all rules with complete audit history and timestamps.
- Catches syntax errors, Levenshtein-distance column misspellings, missing
GROUP BYclauses, and dialect quirks across Postgres, MySQL, BigQuery, Snowflake, and SQLite. - Preserves fix history in
_provenance.healing_trail.
Metabase AI Assistant provides backward and forward compatibility across all major Metabase architectures:
| Metabase Version Range | Compatibility Level | Key Features Supported |
|---|---|---|
| Metabase v0.55 – v0.61+ (Current) | Full Support | Modern MBQL 5 format (stages, lib/type), /api/upload/csv, updated collection permissions, multi-tab dashboards |
| Metabase v0.50 – v0.54 | Full Support | Collection tree hierarchies (/api/collection/tree), Model cards, API Key auth (x-api-key), sequential parametric queries |
| Metabase v0.43 – v0.49 | Full Support | Session token authentication (X-Metabase-Session), legacy MBQL query pipelines, database introspection |
| Metabase Open Source & Enterprise | Full Support | Automatic feature detection (whitelabeling, audit logs, granular data permissions) |
npx metabase-ai-assistantnpm install -g metabase-ai-assistant- Open Claude Desktop Settings -> Developer / Extensions -> Install Local Extension.
- Select this repository folder.
- Or install via Smithery CLI:
npx -y @smithery/cli install metabase-ai-assistant --client claude
Add the server definition to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "metabase-ai-assistant"],
"env": {
"METABASE_URL": "https://your-metabase-instance.com",
"METABASE_API_KEY": "mb_your_api_key_here",
"METABASE_READ_ONLY_MODE": "true"
}
}
}
}Add to .cursor/mcp.json or VS Code MCP settings:
{
"mcpServers": {
"metabase": {
"command": "npx",
"args": ["-y", "metabase-ai-assistant"],
"env": {
"METABASE_URL": "https://your-metabase-instance.com",
"METABASE_API_KEY": "mb_your_api_key_here",
"METABASE_READ_ONLY_MODE": "true"
}
}
}
}Expose Metabase AI Assistant as an OpenAPI Action for ChatGPT Plus / Team / Enterprise:
- Start the Remote SSE/HTTP server:
npm run start:sse - In ChatGPT, create a Custom GPT -> Actions -> Import from URL:
https://your-domain.com/tools/openapi.json - Detailed setup guide: docs/integrations/CHATGPT_ACTIONS_GUIDE.md
Pass tool definitions to Gemini Function Calling SDKs (@google/genai or google-generativeai):
- Detailed setup guide: docs/integrations/GOOGLE_GEMINI_GUIDE.md
Deploy directly to Cloudflare's edge network for free:
cd deploy/cloudflare
npx wrangler deployThe 143 MCP tools are categorized into 10 operational domains:
- dbt & Semantic Layer (6 tools): Model hierarchy inspection, lineage resolution, source prioritization, governance-first business memory (propose, approve, soft-deprecate, restore).
- Autonomous AI BI Operations (4 tools): Self-healing SQL engine, end-to-end dashboard architect, query index advisor, proactive anomaly detector.
- SQL & Query Execution (14 tools): Direct SQL queries, async execution jobs, query status tracking, pagination, and speed benchmarks.
- AI Query Intelligence (6 tools): Natural language to SQL, query performance optimizer, query explainer, automated table description.
- Cards & Visualizations (34 tools): Question creation, query execution, parametric filtering, card cloning, visualization settings.
- Dashboards & Layouts (22 tools): Dashboard creation, grid placement, filter linking, tab management, executive templates.
- Collections & Organization (8 tools): Collection tree traversal, hierarchical moves, permission graphs, item listing.
- Schema & Data Modeling (18 tools): Schema retrieval, foreign key inference, data profiling, table definitions.
- User & Permission Administration (12 tools): User invitations, group assignments, membership controls, status toggling.
- Actions & Documentation (19 tools): Metabase actions execution, pulses, alerts, webhooks, metrics, segment definitions, workspace migration.
Backed by an automated multi-tier test suite covering unit logic, integration workflows, and security fuzzing:
# Run complete test suite (32 suites, 583 tests)
npm test
# Run unit tests
npm run test:unit
# Run integration workflows
npm run test:integration
# Run security & PII zero-leak fuzzing tests
npm run test:securityLicensed under the Apache License 2.0. See the LICENSE file for details.
Developed and maintained by Abdullah Enes SARI (ONMARTECH LLC).