io.github.enessari/metabase-ai-assistant
MCP Server for Metabase - 111 tools for SQL generation, dashboards & PostgreSQL
Open source Open in the app JSON README (API)
About
MCP Server for Metabase - 111 tools for SQL generation, dashboards & PostgreSQL
Details
- Kind
- MCP servers
- Topic
- Databases
- Publisher
- enessari
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.2.0
- Stars
- 49
- Forks
- 10
- Open pull requests
- 1
- Last push
- 2026-09-03T07:53:08Z
- Repository state
- ativo
- Language
- JavaScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:45
- Updated
- 2026-08-29 03:02:45
- Origin id
io.github.enessari/metabase-ai-assistant
README
# Metabase AI Assistant — Model Context Protocol (MCP) Server
[](https://www.npmjs.com/package/metabase-ai-assistant)
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
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)](README.md)**
- 🇹🇷 **[Türkçe Dokümantasyon](README_TR.md)**
- 🇨🇳 **[中文文档 (Chinese)](README_ZH.md)**
- 🇸🇦 **[التوثيق باللغة العربية (Arabic)](README_AR.md)**
---
## Table of Contents
- [Core Architectural Highlights](#core-architectural-highlights)
- [Next-Gen Autonomous Features (v5.3)](#next-gen-autonomous-features-v53)
- [Metabase Version Compatibility](#metabase-version-compatibility)
- [Quick Start & Installation](#quick-start--installation)
- [Client Configuration & Desktop Setup](#client-configuration--desktop-setup)
- [Claude Desktop (One-Click DXT & JSON)](#1-claude-desktop)
- [Cursor IDE, Windsurf & VS Code](#2-cursor-ide-windsurf--vs-code)
- [ChatGPT Custom GPTs & Actions](#3-chatgpt-custom-gpts--actions)
- [Google Gemini & AI Studio](#4-google-gemini--google-ai-studio)
- [Google Antigravity SDK & MCP](#5-google-antigravity-sdk--mcp)
- [Tool Categories Overview (152 Tools)](#tool-categories-overview-152-tools)
- [Testing & Quality Assurance](#testing--quality-assurance)
- [Project Roadmap & Upcoming Features](ROADMAP.md)
- [License](#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
```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](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](docs/integrations/GOOGLE_GEMINI_GUIDE.md)
### 5. Cloudflare Workers (Serverless Edge)
Deploy directly to Cloudflare's edge network for free:
```bash
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:
```bash
# 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](LICENSE) file for details.
Developed and maintained by **Abdullah Enes SARI** ([ONMARTECH LLC](https://github.com/enessari)).