{
  "markdown": "# Metabase AI Assistant — Model Context Protocol (MCP) Server\n \n[![npm version](https://img.shields.io/npm/v/metabase-ai-assistant.svg?style=flat-square)](https://www.npmjs.com/package/metabase-ai-assistant)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg?style=flat-square)](https://nodejs.org/)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-v1.26.0-purple.svg?style=flat-square)](https://modelcontextprotocol.io/)\n\nMetabase 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.\n\nFeaturing **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**.\n\n---\n\n## 🌍 Language Versions / Dil Seçenekleri / 语言版本 / النسخ اللغوية\n\n- 🇬🇧 **[English (Main Documentation)](README.md)**\n- 🇹🇷 **[Türkçe Dokümantasyon](README_TR.md)**\n- 🇨🇳 **[中文文档 (Chinese)](README_ZH.md)**\n- 🇸🇦 **[التوثيق باللغة العربية (Arabic)](README_AR.md)**\n\n---\n\n## Table of Contents\n\n- [Core Architectural Highlights](#core-architectural-highlights)\n- [Next-Gen Autonomous Features (v5.3)](#next-gen-autonomous-features-v53)\n- [Metabase Version Compatibility](#metabase-version-compatibility)\n- [Quick Start & Installation](#quick-start--installation)\n- [Client Configuration & Desktop Setup](#client-configuration--desktop-setup)\n  - [Claude Desktop (One-Click DXT & JSON)](#1-claude-desktop)\n  - [Cursor IDE, Windsurf & VS Code](#2-cursor-ide-windsurf--vs-code)\n  - [ChatGPT Custom GPTs & Actions](#3-chatgpt-custom-gpts--actions)\n  - [Google Gemini & AI Studio](#4-google-gemini--google-ai-studio)\n  - [Google Antigravity SDK & MCP](#5-google-antigravity-sdk--mcp)\n- [Tool Categories Overview (152 Tools)](#tool-categories-overview-152-tools)\n- [Testing & Quality Assurance](#testing--quality-assurance)\n- [Project Roadmap & Upcoming Features](ROADMAP.md)\n- [License](#license)\n\n---\n\n## Core Architectural Highlights\n\nMetabase AI Assistant transforms standard AI interfaces (Claude Desktop, Cursor, VS Code, ChatGPT, Gemini, automated agent frameworks) into full-fledged Metabase power users:\n\n1. **dbt Deep Scanning & MetricFlow Integration (`dbt_project_scan_deep`)**: 9-tier architectural classification, `doc('...')` resolution, and `catalog.json` table/column profiling.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **Autonomous Self-Healing SQL Engine (`ai_sql_execute_and_heal`)**: 3-iteration automated error-recovery loop for resilient querying.\n7. **Zero-Leak Enterprise PII Masker**: Real-time sanitization of emails, phone numbers, national IDs, credit cards, IP addresses, and tokens.\n\n---\n\n## Next-Gen Autonomous Features (v5.1)\n\n### 1. dbt Architectural Hierarchy & Source Prioritization\n$$\\mathbf{Gold\\;Marts\\;(fct\\_,\\;dim\\_,\\;rpt\\_)} \\;\\gg\\; \\mathbf{Silver\\;(int\\_)} \\;\\gg\\; \\mathbf{Bronze\\;Staging\\;(stg\\_)}$$\n- `dbt_inspect_models`: Parses dbt `manifest.json` and MetricFlow semantic models.\n- `dbt_prioritize_sources`: Dynamically routes natural language questions to pre-aggregated, tested dimensional and fact tables.\n\n### 2. Governance-First Semantic Memory (No Silent Learning, No Hard-Deletes)\n- `semantic_memory_propose`: Proposes a business rule in `PENDING_APPROVAL` status.\n- `semantic_memory_approve`: Explicitly activates the rule with required data steward comments.\n- `semantic_memory_deprecate`: Safely soft-archives rules with mandatory audit reasons (`DEPRECATED`).\n- `semantic_memory_restore`: Instantly restores archived rules.\n- `semantic_memory_list`: Lists all rules with complete audit history and timestamps.\n\n### 3. Autonomous Self-Healing SQL Engine (`ai_sql_execute_and_heal`)\n- Catches syntax errors, Levenshtein-distance column misspellings, missing `GROUP BY` clauses, and dialect quirks across Postgres, MySQL, BigQuery, Snowflake, and SQLite.\n- Preserves fix history in `_provenance.healing_trail`.\n\n---\n\n## Metabase Version Compatibility\n\nMetabase AI Assistant provides backward and forward compatibility across all major Metabase architectures:\n\n| Metabase Version Range | Compatibility Level | Key Features Supported |\n|---|:---:|---|\n| **Metabase v0.55 – v0.61+** *(Current)* | **Full Support** | Modern MBQL 5 format (`stages`, `lib/type`), `/api/upload/csv`, updated collection permissions, multi-tab dashboards |\n| **Metabase v0.50 – v0.54** | **Full Support** | Collection tree hierarchies (`/api/collection/tree`), Model cards, API Key auth (`x-api-key`), sequential parametric queries |\n| **Metabase v0.43 – v0.49** | **Full Support** | Session token authentication (`X-Metabase-Session`), legacy MBQL query pipelines, database introspection |\n| **Metabase Open Source & Enterprise** | **Full Support** | Automatic feature detection (whitelabeling, audit logs, granular data permissions) |\n\n---\n\n## Quick Start & Installation\n\n### Global Execution via NPX\n\n```bash\nnpx metabase-ai-assistant\n```\n\n### Manual Installation via NPM\n\n```bash\nnpm install -g metabase-ai-assistant\n```\n\n---\n\n## Client Configuration & Desktop Setup\n\n### 1. Claude Desktop\n\n#### Option A: One-Click Extension (DXT / MCPB)\n1. Open **Claude Desktop Settings** -> **Developer / Extensions** -> **Install Local Extension**.\n2. Select this repository folder.\n3. Or install via Smithery CLI:\n   ```bash\n   npx -y @smithery/cli install metabase-ai-assistant --client claude\n   ```\n\n#### Option B: Manual JSON Configuration\nAdd the server definition to `claude_desktop_config.json`:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"metabase\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"metabase-ai-assistant\"],\n      \"env\": {\n        \"METABASE_URL\": \"https://your-metabase-instance.com\",\n        \"METABASE_API_KEY\": \"mb_your_api_key_here\",\n        \"METABASE_READ_ONLY_MODE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### 2. Cursor IDE, Windsurf & VS Code\n\nAdd to `.cursor/mcp.json` or VS Code MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"metabase\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"metabase-ai-assistant\"],\n      \"env\": {\n        \"METABASE_URL\": \"https://your-metabase-instance.com\",\n        \"METABASE_API_KEY\": \"mb_your_api_key_here\",\n        \"METABASE_READ_ONLY_MODE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### 3. ChatGPT Custom GPTs & Actions\n\nExpose Metabase AI Assistant as an OpenAPI Action for ChatGPT Plus / Team / Enterprise:\n1. Start the Remote SSE/HTTP server: `npm run start:sse`\n2. In ChatGPT, create a **Custom GPT** -> **Actions** -> **Import from URL**: `https://your-domain.com/tools/openapi.json`\n3. Detailed setup guide: [docs/integrations/CHATGPT_ACTIONS_GUIDE.md](docs/integrations/CHATGPT_ACTIONS_GUIDE.md)\n\n### 4. Google Gemini & Google AI Studio\n\nPass tool definitions to Gemini Function Calling SDKs (`@google/genai` or `google-generativeai`):\n- Detailed setup guide: [docs/integrations/GOOGLE_GEMINI_GUIDE.md](docs/integrations/GOOGLE_GEMINI_GUIDE.md)\n\n### 5. Cloudflare Workers (Serverless Edge)\n\nDeploy directly to Cloudflare's edge network for free:\n```bash\ncd deploy/cloudflare\nnpx wrangler deploy\n```\n\n---\n\n## Tool Categories Overview (143 Tools)\n\nThe 143 MCP tools are categorized into 10 operational domains:\n\n1. **dbt & Semantic Layer (6 tools)**: Model hierarchy inspection, lineage resolution, source prioritization, governance-first business memory (propose, approve, soft-deprecate, restore).\n2. **Autonomous AI BI Operations (4 tools)**: Self-healing SQL engine, end-to-end dashboard architect, query index advisor, proactive anomaly detector.\n3. **SQL & Query Execution (14 tools)**: Direct SQL queries, async execution jobs, query status tracking, pagination, and speed benchmarks.\n4. **AI Query Intelligence (6 tools)**: Natural language to SQL, query performance optimizer, query explainer, automated table description.\n5. **Cards & Visualizations (34 tools)**: Question creation, query execution, parametric filtering, card cloning, visualization settings.\n6. **Dashboards & Layouts (22 tools)**: Dashboard creation, grid placement, filter linking, tab management, executive templates.\n7. **Collections & Organization (8 tools)**: Collection tree traversal, hierarchical moves, permission graphs, item listing.\n8. **Schema & Data Modeling (18 tools)**: Schema retrieval, foreign key inference, data profiling, table definitions.\n9. **User & Permission Administration (12 tools)**: User invitations, group assignments, membership controls, status toggling.\n10. **Actions & Documentation (19 tools)**: Metabase actions execution, pulses, alerts, webhooks, metrics, segment definitions, workspace migration.\n\n---\n\n## Testing & Quality Assurance\n\nBacked by an automated multi-tier test suite covering unit logic, integration workflows, and security fuzzing:\n\n```bash\n# Run complete test suite (32 suites, 583 tests)\nnpm test\n\n# Run unit tests\nnpm run test:unit\n\n# Run integration workflows\nnpm run test:integration\n\n# Run security & PII zero-leak fuzzing tests\nnpm run test:security\n```\n\n---\n\n## License\n\nLicensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.\n\nDeveloped and maintained by **Abdullah Enes SARI** ([ONMARTECH LLC](https://github.com/enessari)).\n",
  "bytes": 10651,
  "sha": "6beb03eb3e5848e17b5a0aeefce99b2bb2d1f56d146cf1e7c5cf2265c9d2baa4",
  "repo_slug": "enessari/metabase-ai-assistant",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_enessari_metabase_ai_assistant_a954eddf/readme"
}