metabase-ai-assistant

Metabase AI Assistant — Model Context Protocol（MCP）服务

Metabase AI Assistant 是一款企业级 Model Context Protocol（MCP）服务，可将大模型（LLM）、AI 编码助手和自动化数据工作流直接连接到您的 Metabase 商业智能实例。

它具备 152 个专用工具、原生 dbt 元数据与指标自动同步器、Metabase 到 dbt 的反向血缘暴露、dbt 智能问题创建器、Lightdash Code-as-BI YAML 到仪表板生成、Cube.js 风格的预聚合与多跳血缘联接、Omni.co 受控语义到 YAML 桥接、自主自愈 SQL 执行、全规模仪表板架构设计、主动异常检测、查询索引建议、零泄露 PII 屏蔽以及严格的安全防护措施。它可与 Claude、Cursor、ChatGPT、Gemini 和 Google Antigravity 无缝协作。

---

🌍 语言版本 / 土耳其语文档 / 语言版本 / 阿拉伯语版本

• 🇬🇧 英文（主要文档）
• 🇹🇷 土耳其语文档
• 🇨🇳 中文文档（中文）
• 🇸🇦 阿拉伯语文档（阿拉伯语）

---

目录

• 核心架构亮点
• 新一代自主功能（v5.3）
• Metabase 版本兼容性
• 快速开始与安装
• 客户端配置与桌面端设置
  • Claude Desktop（一键 DXT 与 JSON）
  • Cursor IDE、Windsurf 与 VS Code
  • ChatGPT 自定义 GPT 与操作
  • Google Gemini 与 AI Studio
  • Google Antigravity SDK 与 MCP
• 工具类别概览（152 个工具）
• 测试与质量保证
• 项目路线图与即将推出的功能
• 许可证

---

核心架构亮点

Metabase AI Assistant 可将标准 AI 界面（Claude Desktop、Cursor、VS Code、ChatGPT、Gemini、自动化 Agent 框架）转变为功能完备的 Metabase 高级用户：

1. dbt 深度扫描与 MetricFlow 集成（dbt_project_scan_deep）：9 层架构分类、doc('...') 解析，以及 catalog.json 表/列分析。
2. Cube.js 多跳血缘关系联接（dbt_lineage_joins_graph）：通过 Dijkstra 最小堆算法和三色 DAG 环检测，解析最短联接路径。
3. Cube.js 预聚合与汇总表顾问（dbt_semantic_preagg_advisor）：生成多种方言的物化视图 DDL（Postgres、BigQuery、Snowflake、ClickHouse、DuckDB、Redshift、MySQL），并支持 HyperLogLog 去重计数。
4. Lightdash 代码即 BI 仪表板构建器（dbt_build_dashboard_from_yaml）：将 meta.metabase 和 meta.lightdash 格式选项转换为互不冲突的 24 列 Metabase 仪表板。
5. Omni.co 受控语义到 YAML 导出器（dbt_semantic_export_yaml）：将已批准的业务规则序列化为简洁的 dbt schema.yml / semantic_models.yml 代码块。
6. 自主自愈 SQL 引擎（ai_sql_execute_and_heal）：通过 3 轮自动错误恢复循环，实现稳健查询。
7. 零泄漏企业 PII 脱敏器：实时清理电子邮件、电话号码、国家 ID、信用卡号、IP 地址和令牌。

---

新一代自主功能（v5.1）

1. dbt 架构层级与数据源优先级

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

• dbt_inspect_models：解析 dbt manifest.json 和 MetricFlow 语义模型。
• dbt_prioritize_sources：动态将自然语言问题路由到经过预聚合和测试的维度表与事实表。

2. 治理优先的语义记忆（不静默学习，不永久删除）

• semantic_memory_propose：以 PENDING_APPROVAL 状态提出业务规则。
• semantic_memory_approve：通过必填的数据管理人员评论，明确激活规则。
• semantic_memory_deprecate：安全地软归档规则，并要求填写审计原因（DEPRECATED）。
• semantic_memory_restore：立即恢复已归档的规则。
• semantic_memory_list：列出所有规则及完整审计历史和时间戳。

3. 自主自愈 SQL 引擎（ai_sql_execute_and_heal）

• 捕获语法错误、基于 Levenshtein 距离的列名拼写错误、缺失的 GROUP BY 子句，以及 Postgres、MySQL、BigQuery、Snowflake 和 SQLite 中的方言差异。
• 在 _provenance.healing_trail 中保留修复历史。

---

Metabase 版本兼容性

Metabase AI Assistant 可兼容所有主要 Metabase 架构的旧版本和新版本：

Metabase 版本范围	兼容级别	支持的主要功能
Metabase v0.55 – v0.61+ （当前）	全面支持	现代 MBQL 5 格式（stages、lib/type）、/api/upload/csv、更新后的集合权限、多标签仪表板
Metabase v0.50 – v0.54	全面支持	集合树层级（/api/collection/tree）、模型卡片、API Key 身份验证（x-api-key）、顺序参数化查询
Metabase v0.43 – v0.49	全面支持	会话令牌身份验证（X-Metabase-Session）、旧版 MBQL 查询管道、数据库内省
Metabase 开源版与企业版	全面支持	自动检测功能（白标、审计日志、细粒度数据权限）

---

快速开始与安装

通过 NPX 全局执行

npx metabase-ai-assistant

通过 NPM 手动安装

npm install -g metabase-ai-assistant

---

客户端配置与桌面端设置

1. Claude Desktop

选项 A：一键扩展（DXT / MCPB）

1. 打开 Claude Desktop Settings -> Developer / Extensions -> Install Local Extension。
2. 选择此仓库文件夹。
3. 或通过 Smithery CLI 安装：

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

选项 B：手动配置 JSON

将服务定义添加到 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

添加到 .cursor/mcp.json 或 VS Code MCP 设置中：

{
  "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 自定义 GPT 和 Actions

将 Metabase AI Assistant 作为 OpenAPI Action 提供给 ChatGPT Plus / Team / Enterprise：

1. 启动远程 SSE/HTTP 服务：npm run start:sse
2. 在 ChatGPT 中，创建一个 Custom GPT -> Actions -> Import from URL：https://your-domain.com/tools/openapi.json
3. 详细设置指南：docs/integrations/CHATGPT_ACTIONS_GUIDE.md

4. Google Gemini 和 Google AI Studio

将工具定义传递给 Gemini Function Calling SDK（@google/genai 或 google-generativeai）：

• 详细设置指南：docs/integrations/GOOGLE_GEMINI_GUIDE.md

5. Cloudflare Workers（无服务器边缘计算）

直接免费部署到 Cloudflare 边缘网络：

cd deploy/cloudflare
npx wrangler deploy

---

工具类别概览（143 个工具）

143 个 MCP 工具分为 10 个操作领域：

1. dbt 和语义层（6 个工具）：模型层级检查、血缘解析、源优先级排序、治理优先的业务记忆（提议、批准、软弃用、恢复）。
2. 自主 AI BI 运维（4 个工具）：自愈 SQL 引擎、端到端仪表板架构师、查询索引顾问、主动异常检测器。
3. SQL 和查询执行（14 个工具）：直接 SQL 查询、异步执行任务、查询状态跟踪、分页和速度基准测试。
4. AI 查询智能（6 个工具）：自然语言转 SQL、查询性能优化器、查询解释器、自动表描述。
5. 卡片和可视化（34 个工具）：创建问题、执行查询、参数化筛选、克隆卡片、可视化设置。
6. 仪表板和布局（22 个工具）：创建仪表板、网格布局、筛选器关联、标签页管理、高管模板。
7. 集合和组织（8 个工具）：遍历集合树、层级移动、权限图、项目列表。
8. 架构和数据建模（18 个工具）：获取架构、推断外键、数据分析、表定义。
9. 用户和权限管理（12 个工具）：邀请用户、分配群组、成员资格控制、切换状态。
10. Actions 和文档（19 个工具）：执行 Metabase actions、pulses、alerts、webhooks、metrics、segment 定义、工作区迁移。

---

测试与质量保证

由自动化多层测试套件提供支持，覆盖单元逻辑、集成工作流和安全模糊测试：

# 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

---

许可证

根据 Apache License 2.0 许可。详情请参阅 LICENSE 文件。

由 Abdullah Enes SARI (ONMARTECH LLC) 开发并维护。