io.github.enessari/metabase-ai-assistant

Metabase AI Assistant — Model Context Protocol (MCP) Server

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 152 dedicated tools, native dbt Metadata & Metrics Auto-Syncer, Metabase to dbt Reverse Lineage Exposures, dbt-Smart Question Creator, Lightdash Code-as-BI YAML-to-Dashboard generation, Cube.js-style Pre-aggregations & Multi-Hop Lineage Joins, Omni.co Controlled Semantic-to-YAML bridge, autonomous self-healing SQL execution, full-scale dashboard architecting, proactive anomaly detection, query index advisory, zero-leak PII masking, and strict security guardrails. Works seamlessly with Claude, Cursor, ChatGPT, Gemini, and Google Antigravity.

---

🌍 Language Versions / Dil Seçenekleri / 语言版本 / النسخ اللغوية

• 🇬🇧 English (Main Documentation)
• 🇹🇷 Türkçe Dokümantasyon
• 🇨🇳 中文文档 (Chinese)
• 🇸🇦 التوثيق باللغة العربية (Arabic)

---

Table of Contents

• Core Architectural Highlights
• Next-Gen Autonomous Features (v5.3)
• Metabase Version Compatibility
• Quick Start & Installation
• Client Configuration & Desktop Setup
  • Claude Desktop (One-Click DXT & JSON)
  • Cursor IDE, Windsurf & VS Code
  • ChatGPT Custom GPTs & Actions
  • Google Gemini & AI Studio
  • Google Antigravity SDK & MCP
• Tool Categories Overview (152 Tools)
• Testing & Quality Assurance
• Project Roadmap & Upcoming Features
• License

---

Core Architectural Highlights

Metabase AI Assistant transforms standard AI interfaces (Claude Desktop, Cursor, VS Code, ChatGPT, Gemini, automated agent frameworks) into full-fledged Metabase power users:

1. dbt Deep Scanning & MetricFlow Integration (dbt_project_scan_deep): 9-tier architectural classification, doc('...') resolution, and catalog.json table/column profiling.
2. Cube.js Multi-Hop Lineage Joins (dbt_lineage_joins_graph): Resolves shortest join paths via Dijkstra Min-Heap algorithms with 3-color DAG cycle detection.
3. Cube.js Pre-Aggregation & Rollup Advisor (dbt_semantic_preagg_advisor): Generates multi-dialect Materialized View DDLs (Postgres, BigQuery, Snowflake, ClickHouse, DuckDB, Redshift, MySQL) with HyperLogLog distinct counts.
4. Lightdash Code-as-BI Dashboard Builder (dbt_build_dashboard_from_yaml): Translates meta.metabase and meta.lightdash formatting options into collision-free 24-column Metabase Dashboards.
5. Omni.co Controlled Semantic-to-YAML Exporter (dbt_semantic_export_yaml): Serializes approved business rules into clean dbt schema.yml / semantic_models.yml code blocks.
6. Autonomous Self-Healing SQL Engine (ai_sql_execute_and_heal): 3-iteration automated error-recovery loop for resilient querying.
7. Zero-Leak Enterprise PII Masker: Real-time sanitization of emails, phone numbers, national IDs, credit cards, IP addresses, and tokens.

---

Next-Gen Autonomous Features (v5.1)

1. dbt Architectural Hierarchy & Source Prioritization

$$\mathbf{Gold;Marts;(fct_,;dim_,;rpt_)} ;\gg; \mathbf{Silver;(int_)} ;\gg; \mathbf{Bronze;Staging;(stg_)}$$

• dbt_inspect_models: Parses dbt manifest.json and MetricFlow semantic models.
• dbt_prioritize_sources: Dynamically routes natural language questions to pre-aggregated, tested dimensional and fact tables.

2. Governance-First Semantic Memory (No Silent Learning, No Hard-Deletes)

• semantic_memory_propose: Proposes a business rule in PENDING_APPROVAL status.
• 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.

3. Autonomous Self-Healing SQL Engine (ai_sql_execute_and_heal)

• Catches syntax errors, Levenshtein-distance column misspellings, missing GROUP BY clauses, and dialect quirks across Postgres, MySQL, BigQuery, Snowflake, and SQLite.
• Preserves fix history in _provenance.healing_trail.

---

Metabase Version Compatibility

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)

---

Quick Start & Installation

Global Execution via NPX

npx metabase-ai-assistant

Manual Installation via NPM

npm install -g metabase-ai-assistant

---

Client Configuration & Desktop Setup

1. Claude Desktop

Option A: One-Click Extension (DXT / MCPB)

1. Open Claude Desktop Settings -> Developer / Extensions -> Install Local Extension.
2. Select this repository folder.
3. Or install via Smithery CLI:

   npx -y @smithery/cli install metabase-ai-assistant --client claude
   

Option B: Manual JSON Configuration

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"
      }
    }
  }
}

2. Cursor IDE, Windsurf & VS Code

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"
      }
    }
  }
}

3. ChatGPT Custom GPTs & Actions

Expose Metabase AI Assistant as an OpenAPI Action for ChatGPT Plus / Team / Enterprise:

1. Start the Remote SSE/HTTP server: npm run start:sse
2. In ChatGPT, create a Custom GPT -> Actions -> Import from URL: https://your-domain.com/tools/openapi.json
3. Detailed setup guide: docs/integrations/CHATGPT_ACTIONS_GUIDE.md

4. Google Gemini & Google AI Studio

Pass tool definitions to Gemini Function Calling SDKs (@google/genai or google-generativeai):

• Detailed setup guide: docs/integrations/GOOGLE_GEMINI_GUIDE.md

5. Cloudflare Workers (Serverless Edge)

Deploy directly to Cloudflare's edge network for free:

cd deploy/cloudflare
npx wrangler deploy

---

Tool Categories Overview (143 Tools)

The 143 MCP tools are categorized into 10 operational domains:

1. dbt & Semantic Layer (6 tools): Model hierarchy inspection, lineage resolution, source prioritization, governance-first business memory (propose, approve, soft-deprecate, restore).
2. Autonomous AI BI Operations (4 tools): Self-healing SQL engine, end-to-end dashboard architect, query index advisor, proactive anomaly detector.
3. SQL & Query Execution (14 tools): Direct SQL queries, async execution jobs, query status tracking, pagination, and speed benchmarks.
4. AI Query Intelligence (6 tools): Natural language to SQL, query performance optimizer, query explainer, automated table description.
5. Cards & Visualizations (34 tools): Question creation, query execution, parametric filtering, card cloning, visualization settings.
6. Dashboards & Layouts (22 tools): Dashboard creation, grid placement, filter linking, tab management, executive templates.
7. Collections & Organization (8 tools): Collection tree traversal, hierarchical moves, permission graphs, item listing.
8. Schema & Data Modeling (18 tools): Schema retrieval, foreign key inference, data profiling, table definitions.
9. User & Permission Administration (12 tools): User invitations, group assignments, membership controls, status toggling.
10. Actions & Documentation (19 tools): Metabase actions execution, pulses, alerts, webhooks, metrics, segment definitions, workspace migration.

---

Testing & Quality Assurance

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:security

---

License

Licensed under the Apache License 2.0. See the LICENSE file for details.

Developed and maintained by Abdullah Enes SARI (ONMARTECH LLC).