STARWARCLOUD STARWAR.AI
返回市场
元数据库人工智能助手

元数据库人工智能助手

作者：enessari9 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

技术文档摘要

Metabase AI 助手 🤖

MIT License Node.js MCP 兼容 GitHub stars GitHub forks

通过 Model Context Protocol (MCP) 直接连接到 Metabase 和 PostgreSQL 数据库，为 Claude Desktop 和 Claude Code 提供支持。使用 Metabase API 和直接数据库连接创建模型、SQL 查询、指标和仪表板。

🚀 适用于 Claude Desktop & Claude Code 的 MCP 服务器 - Metabase + 直接数据库访问
⭐ 如果你觉得这个项目有用，请给它一个星！ ⭐

🚀 特性

🔌 MCP 集成（Claude Desktop & Claude Code）

  • 模型上下文协议：与 Claude Desktop 和 Claude Code 原生集成
  • 直接数据库访问：直接连接 PostgreSQL 数据库
  • Metabase API 集成：完全集成到 Metabase 实例中
  • 模式发现：自动数据库模式发现和分析
  • 关系检测：表关系检测和建议

🤖 AI 功能

  • 自然语言 SQL：从自然语言描述生成 SQL 查询
  • 智能模型构建：AI 辅助的 Metabase 模型创建
  • 智能仪表板：自动仪表板布局和小部件建议
  • 查询优化：SQL 查询性能优化
  • 数据洞察：数据分析和模式检测

🛠️ 开发者工具

  • DDL 操作：安全地创建表/视图/索引（前缀保护）
  • 批处理操作：批量数据处理操作
  • 连接管理：混合连接管理（API + 直接）
  • 安全控制：AI 对象前缀控制和审批工作流
  • 性能监控：操作计时和超时控制

📋 要求

🖥️ 系统

  • Node.js 18+
  • Claude Desktop（用于 MCP 支持）或 Claude Code
  • PostgreSQL 数据库（用于直接连接）

🔗 服务

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

🔧 安装

# 克隆仓库
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 中。

🔌 Claude Desktop & Claude Code 集成（MCP）

该项目通过 Model Context Protocol (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"
      }
    }
  }
}
  1. 重启 Claude Desktop，MCP 工具将可用。

对于 Claude Code：

Claude Code 可以通过全局安装直接使用此 MCP 服务器：

第一步：全局安装

# 全局安装 MCP 服务器
npm link

# 验证安装
which metabase-ai-mcp
npm list -g | grep metabase-ai-assistant

第二步：环境设置

确保你的 .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

第三步：测试 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

第四步：验证集成

在 Claude Code 中询问：“你有哪些可用的 MCP 工具？”

你应该看到有 27 个 Metabase AI 助手工具 可用：

📊 数据库工具：

  • 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 功能工具：

  • 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 文档爬取和搜索
  • 表关系检测和映射

🎯 使用方法

交互式 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(
  '预算 vs 实际',
  budgetQuestions
);

🛠️ CLI 命令

交互式 CLI 中可用的命令：

  • 📊 创建模型：使用 AI 创建模型
  • ❓ 创建问题：生成 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

🔒 安全

数据安全

  • 环境变量：所有敏感数据（API 密钥、密码）存储在 .env 文件中
  • Git 忽略：.env 文件排除在版本控制之外
  • SQL 注入防护：参数化查询和输入验证
  • 速率限制：应用 API 请求速率限制
  • 审计日志：记录所有数据库操作以进行安全监控
  • 无硬编码凭据：安全优先的方法防止凭据暴露

数据库安全

  • AI 对象前缀：所有 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 文件提交到版本控制系统
  • 避免在源代码中硬编码凭据
  • 使用前缀验证 AI 创建的对象
  • 监控数据库操作以符合安全规定

🚀 生产部署

选项 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. 创建 Pull Request

💡 贡献想法

  • 新的 AI 模型集成
  • 仪表板模板
  • Metabase 连接器
  • 文档改进
  • Bug 修复和性能优化

📋 贡献规则

  • 在代码更改时编写测试
  • 使用 Conventional Commits 编写提交信息
  • 遵守 ESLint 和 Prettier 设置
  • 记录你的更改

📄 许可

MIT 许可 - 详情请