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团队 - 提供优秀的平台
• 开源社区 - 持续的灵感和反馈

🌟 名人堂

做出重要贡献的开发者将在此列出。

如果您觉得这个项目有用，请不要忘记点个 ⭐ 星并 🔄 分享！