Metabase Ai Assistant

🚀 Metabase AI Assistant 🤖

Metabase AI Assistant是一款由人工智能驅動的助手，它通過模型上下文協議（MCP） 直接連接到Metabase和PostgreSQL數據庫，適用於Claude Desktop和Claude Code。該助手能夠利用Metabase API和直接數據庫連接來創建模型、SQL查詢、指標和儀表板。

🚀 適用於Claude Desktop和Claude Code的MCP服務器 - 支持Metabase和直接數據庫訪問
⭐ 如果您覺得這個項目有用，請給它點個星！ ⭐

🚀 快速開始

本項目可通過以下簡單步驟快速啟動。首先，按照安裝指南完成項目的安裝和依賴配置；接著，根據配置說明設置好環境變量；然後，依據Claude Desktop和Claude Code集成步驟完成與這兩個工具的集成；最後，根據不同的使用場景選擇交互式CLI或者編程式使用方式來使用本項目。

✨ 主要特性

🔌 MCP集成（Claude Desktop和Claude Code）

• 模型上下文協議：與Claude Desktop和Claude Code進行原生集成
• 直接數據庫訪問：可直接連接到PostgreSQL數據庫
• Metabase API集成：與Metabase實例進行全面集成
• 模式發現：自動發現和分析數據庫模式
• 關係檢測：檢測表之間的關係並提供建議

🤖 人工智能驅動的特性

• 自然語言SQL：根據自然語言描述生成SQL查詢
• 智能模型構建：在人工智能的輔助下創建Metabase模型
• 智能儀表板：自動佈局儀表板並提供小部件建議
• 查詢優化：優化SQL查詢的性能
• 數據洞察：進行數據分析並檢測數據模式

🛠️ 開發者工具

• DDL操作：安全地創建表、視圖和索引（帶有前綴保護）
• 批量操作：進行批量數據處理操作
• 連接管理：混合連接管理（API + 直接連接）
• 安全控制：通過人工智能對象前綴控制和審批工作流確保安全
• 性能監控：控制操作的時間和超時

📦 安裝指南

# 克隆倉庫
git clone https://github.com/onmartech/metabase-ai-assistant.git
cd metabase-ai-assistant

# 安裝依賴
npm install

# 創建環境文件
cp .env.example .env

⚙️ 配置

編輯 .env 文件：

# Metabase配置
METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_metabase_api_key

# AI提供商（至少需要一個）
ANTHROPIC_API_KEY=your_anthropic_key
# 或者
OPENAI_API_KEY=your_openai_key

# 應用設置
LOG_LEVEL=info

⚠️ 重要提示

切勿將 .env 文件提交到版本控制中，該文件已包含在 .gitignore 中。

💻 使用示例

交互式CLI

npm start

編程式使用

import { MetabaseClient } from './src/metabase/client.js';
import { MetabaseAIAssistant } from './src/ai/assistant.js';

// 創建客戶端
const client = new MetabaseClient({
  url: 'http://your-metabase.com',
  username: 'user',
  password: 'pass'
});

// 啟動AI助手
const assistant = new MetabaseAIAssistant({
  metabaseClient: client,
  aiProvider: 'anthropic',
  anthropicApiKey: 'your-key'
});

// 創建模型
const model = await assistant.createModel(
  '客戶細分模型',
  databaseId
);

// 生成SQL查詢
const sql = await assistant.generateSQL(
  '最近30天的銷售總額',
  schema
);

示例場景

1. 電子商務儀表板

// 創建銷售模型
await assistant.createModel(
  '每日銷售摘要 - 產品、類別、金額',
  databaseId
);

// 定義指標
await assistant.createMetric(
  '平均訂單價值',
  tableId
);

// 創建儀表板
await assistant.createDashboard(
  '電子商務管理面板',
  questions
);

2. 客戶分析

// 客戶細分查詢
const sql = await assistant.generateSQL(
  '通過RFM分析進行客戶細分',
  schema
);

// 客戶流失預測模型
await assistant.createModel(
  '客戶流失預測模型',
  databaseId
);

3. 財務報告

// 收支分析
await assistant.createQuestion(
  '月度損益表',
  databaseId
);

// 預算對比儀表板
await assistant.createDashboard(
  '預算與實際情況對比',
  budgetQuestions
);

📚 詳細文檔

📋 要求

🖥️ 系統

• Node.js 18+
• Claude Desktop（用於MCP支持）或 Claude Code
• PostgreSQL數據庫（用於直接連接）

🔗 服務

• Metabase實例（v0.48+）
• Anthropic API（包含在Claude Desktop/Code中）

🛠️ CLI命令

在交互式CLI中可用的命令如下：

• 📊 創建模型：使用人工智能創建模型
• ❓ 創建問題：創建SQL查詢
• 📈 創建指標：定義指標
• 📋 創建儀表板：準備儀表板
• 🔍 探索模式：探索數據庫模式
• 🚀 執行SQL：執行SQL查詢
• 🔧 優化查詢：優化查詢
• 💡 AI查詢構建器：使用自然語言創建查詢

📂 項目結構

metabase-ai-assistant/
├── src/
│   ├── mcp/
│   │   └── server.js        # MCP服務器（Claude Desktop集成）
│   ├── metabase/
│   │   └── client.js        # Metabase API客戶端
│   ├── database/
│   │   ├── direct-client.js     # 直接PostgreSQL客戶端
│   │   └── connection-manager.js # 混合連接管理器
│   ├── ai/
│   │   └── assistant.js     # AI輔助函數
│   ├── cli/
│   │   └── interactive.js   # 交互式CLI（獨立運行）
│   ├── utils/
│   │   └── logger.js        # 日誌記錄工具
│   └── index.js             # 主入口點（CLI模式）
├── tests/                    # 測試文件
├── .env.example             # 環境模板
├── package.json
└── README.md

🔍 API參考

MetabaseClient

// 數據庫
getDatabases()
getDatabase(id)
getDatabaseSchemas(databaseId)
getDatabaseTables(databaseId)

// 模型
getModels()
createModel(modelData)

// 查詢
getQuestions(collectionId)
createQuestion(questionData)
executeNativeQuery(databaseId, sql)

// 指標
getMetrics()
createMetric(metricData)

// 儀表板
getDashboards()
createDashboard(dashboardData)
addCardToDashboard(dashboardId, cardId, options)

MetabaseAIAssistant

// AI操作
analyzeRequest(userRequest)
generateSQL(description, schema)
suggestVisualization(data, questionType)
optimizeQuery(sql)
explainQuery(sql)

// 創建操作
createModel(description, databaseId)
createQuestion(description, databaseId, collectionId)
createMetric(description, tableId)
createDashboard(description, questions)

🧪 測試

# 運行所有測試
npm test

# 連接測試
npm run test:connection

# 覆蓋率報告
npm run test:coverage

🔌 Claude Desktop和Claude Code集成（MCP）

本項目通過模型上下文協議（MCP）與Claude Desktop和Claude Code集成。

對於Claude Desktop：

1. 編輯Claude Desktop配置：~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "metabase-ai-assistant": {
      "command": "node",
      "args": ["/path/to/your/metabase-ai-assistant/src/mcp/server.js"],
      "env": {
        "METABASE_URL": "http://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password",
        "ANTHROPIC_API_KEY": "your_anthropic_key"
      }
    }
  }
}

2. 重啟Claude Desktop，即可使用MCP工具。

對於Claude Code：

Claude Code可以通過全局安裝直接使用此MCP服務器。

步驟1：全局安裝

# 全局安裝MCP服務器
npm link

# 驗證安裝
which metabase-ai-mcp
npm list -g | grep metabase-ai-assistant

步驟2：環境設置

確保您的 .env 文件已正確配置Metabase憑證：

METABASE_URL=http://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
METABASE_API_KEY=your_api_key
ANTHROPIC_API_KEY=your_anthropic_key

步驟3：測試MCP服務器

# 直接測試MCP服務器
node src/mcp/server.js

# 使用環境變量進行測試
export METABASE_URL="http://your-instance.com"
export METABASE_USERNAME="your_username"
export METABASE_PASSWORD="your_password"
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node src/mcp/server.js

步驟4：驗證集成

在Claude Code中，詢問："您有哪些可用的MCP工具？"

您應該會看到 27個Metabase AI Assistant工具 可用： 📊 數據庫工具:

• db_list - 列出所有Metabase數據庫
• db_schemas - 獲取模式信息
• db_tables - 列出帶有詳細信息的表
• sql_execute - 運行SQL查詢

🎯 Metabase工具:

• mb_question_create - 創建問題/圖表
• mb_dashboard_create - 創建儀表板
• mb_dashboard_template_executive - 自動生成執行儀表板
• mb_question_create_parametric - 創建參數化問題

🔍 人工智能驅動的工具:

• ai_sql_generate - 根據自然語言生成SQL
• ai_sql_optimize - 優化SQL性能
• ai_sql_explain - 解釋SQL查詢

📚 文檔工具:

• web_explore_metabase_docs - 爬取Metabase文檔
• web_search_metabase_docs - 搜索文檔

該服務器提供了全面的Metabase和PostgreSQL集成，擁有 27個工具，可用於：

• 數據庫模式探索和分析
• 自然語言SQL查詢生成和優化
• 執行儀表板模板和參數化問題
• 帶有安全控制的直接DDL操作
• Metabase文檔爬取和搜索
• 表關係檢測和映射

🔧 技術細節

🔒 安全

數據安全

• 環境變量：所有敏感數據（API密鑰、密碼）都存儲在 .env 文件中
• Git忽略：.env 文件被排除在版本控制之外
• SQL注入防護：使用參數化查詢和輸入驗證
• 速率限制：對API請求應用速率限制
• 審計日誌：記錄所有數據庫操作以進行安全監控
• 無硬編碼憑證：採用安全優先的方法防止憑證洩露

數據庫安全

• AI對象前綴：所有由人工智能創建的對象都帶有 claude_ai_ 前綴以確保安全
• 模式隔離：操作僅限於指定的模式
• 只讀模式：默認具有隻讀權限，修改操作需要明確批准
• DDL審批系統：數據庫更改需要明確確認
• 前綴驗證：只有帶有AI前綴的對象才能被修改或刪除

MCP安全

• 安全傳輸：MCP通信通過安全通道進行
• 環境隔離：通過環境變量傳遞憑證
• 工具驗證：在執行所有工具輸入之前進行驗證
• 錯誤處理：從錯誤消息中過濾敏感信息

生產部署

• 使用特定於環境的配置文件
• 所有數據庫通信都使用SSL/TLS連接
• 為數據庫用戶授予最小必要的權限
• 使用身份驗證和授權保護API端點
• 定期輪換API密鑰和數據庫密碼
• 監控和記錄所有工具使用情況以進行安全審計

🐛 故障排除

連接錯誤

• 驗證Metabase URL是否可訪問
• 確保API密鑰和憑證有效
• 檢查網絡連接和防火牆設置
• 確認環境變量已正確設置

MCP集成問題

• 確保 npm link 已成功運行
• 驗證MCP服務器二進制文件是否在PATH中：which metabase-ai-mcp
• 檢查環境變量是否已導出：echo $METABASE_URL
• 直接測試MCP服務器：node src/mcp/server.js
• 全局安裝後重啟Claude Code

查詢錯誤

• 驗證SQL語法和格式
• 確認表和列名是否存在
• 檢查數據庫權限和模式訪問
• 確保操作選擇了正確的模式

安全警告

• 切勿將 .env 文件提交到版本控制中
• 避免在源代碼中硬編碼憑證
• 對人工智能創建的對象使用前綴驗證
• 監控數據庫操作以確保安全合規

🚀 生產部署

選項1：PM2進程管理器（推薦）

# 全局安裝PM2
npm install -g pm2

# 使用PM2啟動MCP服務器
npm run pm2:start

# 監控和管理
npm run pm2:logs
npm run pm2:restart
npm run pm2:stop

# 系統重啟時自動重啟
pm2 startup
pm2 save

選項2：Docker容器

# 使用Docker Compose構建和運行
npm run docker:run

# 監控日誌
npm run docker:logs

# 停止容器
npm run docker:stop

選項3：雲部署

• Railway：使用 railway.json 進行一鍵部署
• Heroku：使用Heroku CLI進行部署（請參閱 deploy/heroku-deploy.md）
• DigitalOcean：使用App Platform和Docker
• AWS：使用ECS Fargate或EC2和systemd服務

選項4：Systemd服務（Linux）

# 複製服務文件
sudo cp metabase-ai-mcp.service /etc/systemd/system/

# 啟用並啟動服務
sudo systemctl enable metabase-ai-mcp
sudo systemctl start metabase-ai-mcp

# 監控服務
sudo systemctl status metabase-ai-mcp
sudo journalctl -u metabase-ai-mcp -f

生產腳本

npm run mcp:prod          # 生產模式
npm run test:connection   # 健康檢查
npm run lint             # 代碼質量檢查

📈 路線圖

• [ ] 自然語言處理改進
• [ ] 可視化查詢構建器
• [ ] 自動儀表板推薦系統
• [ ] 多數據庫支持
• [ ] 即時數據流
• [ ] 高級機器學習模型

🤝 貢獻

如果您喜歡這個項目並希望為其發展做出貢獻，可以參考以下內容：

⭐ 支持項目

• 在GitHub上點星：如果您覺得項目有用，請點個 ⭐ 星
• 關注我們：關注 @onmartech 賬號以獲取更新
• 分享項目：在社交媒體上分享並推薦給您的朋友

🔧 參與開發

1. Fork 項目
2. 創建 功能分支 (git checkout -b feature/new-feature)
3. 提交更改 (git commit -m 'feat: 添加新功能')
4. 推送更改 (git push origin feature/new-feature)
5. 創建拉取請求

💡 貢獻想法

• 集成新的AI模型
• 開發儀表板模板
• 開發Metabase連接器
• 改進文檔
• 修復Bug和優化性能

📋 貢獻規則

• 在進行代碼更改時編寫測試
• 在提交消息中使用 Conventional Commits
• 遵循ESLint和Prettier設置
• 記錄您的更改

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。 版權所有 (c) 2024 ONMARTECH LLC

👥 支持與聯繫

🐛 Bug報告和功能請求

• GitHub Issues：問題頁面
• Bug模板：在創建問題時使用模板
• 功能請求：詳細描述您需要的功能

💬 社區

• GitHub討論：用於問答和分享想法
• 文檔：為Wiki頁面做出貢獻
• 示例：分享示例使用案例

🚀 商業支持

ONMARTECH LLC提供專業的支持和定製服務。

🏆 貢獻者

感謝所有使這個項目成為可能的人：

• ONMARTECH LLC - 項目開發和維護
• Metabase團隊 - 提供優秀的平臺
• 開源社區 - 持續的靈感和反饋

🌟 名人堂

做出重要貢獻的開發者將在此列出。

如果您覺得這個項目有用，請不要忘記點個 ⭐ 星並 🔄 分享！