Metabase Ai Assistant

io.github.enessariPublished by GitHub account enessariv3.2.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyDatabasesProductivity & WorkflowData & Analytics

Overview

AI-generated overview

Connects an AI assistant to a Metabase BI instance for SQL, dashboards, cards, collections, and dbt semantic-layer work.

What you can do
Exposes a large tool set (the README claims 143-152 tools) covering SQL and query execution, natural-language-to-SQL, card and visualization management, dashboard building and layout, collection organization, schema and data modeling, user and permission administration, and alerts, pulses, and actions. It also adds dbt and semantic-layer features such as model inspection, lineage joins, pre-aggregation advice, YAML-to-dashboard generation, and a governance-first semantic memory with propose, approve, deprecate, and restore steps. A self-healing SQL loop retries failed queries, and a PII masker sanitizes emails, phone numbers, IDs, cards, IPs, and tokens.
When to use it
Use it when an assistant needs to work inside an existing Metabase deployment: exploring schemas, writing and running SQL, creating or editing questions and dashboards, organizing collections, or managing users and permissions. It also suits teams that keep dbt or MetricFlow semantic models and want the assistant to read them and generate dashboards or YAML.
Requirements
Runs locally over stdio, typically via npx or a global npm install, so Node.js is needed. Requires METABASE_URL and either METABASE_API_KEY or METABASE_USERNAME with METABASE_PASSWORD. Direct PostgreSQL SQL execution needs DATABASE_HOST, DATABASE_NAME, DATABASE_PORT, DATABASE_USER, and DATABASE_PASSWORD. Network access to the Metabase instance is required.
Before you install
It holds credentials for a BI system and, optionally, a database: METABASE_API_KEY, METABASE_PASSWORD, and DATABASE_PASSWORD. Many tools write or change data, including creating and editing cards and dashboards, moving collections, inviting users, changing group memberships and status, and running Metabase actions, pulses, and webhooks. Direct SQL execution can modify the PostgreSQL database. The README shows a read-only mode flag, but it is not listed among the declared environment variables…

Installation

In SourceWeft

  1. Open Metabase Ai Assistant in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Metabase AI Assistant — Model Context Protocol (MCP) Server

[npm version] [License] [Node.js] [MCP SDK]

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 / 语言版本 / النسخ اللغوية

Table of Contents

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 RangeCompatibility LevelKey Features Supported
Metabase v0.55 – v0.61+ (Current)Full SupportModern MBQL 5 format (stages, lib/type), /api/upload/csv, updated collection permissions, multi-tab dashboards
Metabase v0.50 – v0.54Full SupportCollection tree hierarchies (/api/collection/tree), Model cards, API Key auth (x-api-key), sequential parametric queries
Metabase v0.43 – v0.49Full SupportSession token authentication (X-Metabase-Session), legacy MBQL query pipelines, database introspection
Metabase Open Source & EnterpriseFull SupportAutomatic feature detection (whitelabeling, audit logs, granular data permissions)

Quick Start & Installation

Global Execution via NPX

bash
npx metabase-ai-assistant

Manual Installation via NPM

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

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

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

5. Cloudflare Workers (Serverless Edge)

Deploy directly to Cloudflare's edge network for free:

bash
cd deploy/cloudflarenpx 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:

bash
# Run complete test suite (32 suites, 583 tests)npm test
# Run unit testsnpm run test:unit
# Run integration workflowsnpm run test:integration
# Run security & PII zero-leak fuzzing testsnpm 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).

Source: README.md at commit 009ae02

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v3.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts