Metabase MCP 服务器

作者: Hyeongjun Yu (@hyeongjun-dev)

这是一个将AI助手与Metabase分析平台集成的模型上下文协议服务器。

概述

这个基于TypeScript的MCP服务器提供了与Metabase API的无缝集成，使AI助手能够直接与您的分析数据进行交互。该服务器专为Claude和其他兼容MCP的AI助手设计，作为您的分析平台与对话式AI之间的桥梁。

主要特性

• 资源访问: 通过直观的metabase://URI导航Metabase资源
• 两种认证方法: 支持基于会话和API密钥的认证
• 结构化数据访问: 以JSON格式响应，便于AI助手消费
• 全面的日志记录: 详细的日志记录，便于调试和监控
• 错误处理: 健壮的错误处理机制，带有清晰的错误信息

可用工具

该服务器向AI助手暴露了以下工具：

• list_dashboards: 获取您Metabase实例中的所有可用仪表板
• list_cards: 获取Metabase中保存的所有问题/卡片
• list_databases: 查看所有连接的数据库源
• execute_card: 运行保存的问题并获取结果，可选参数
• get_dashboard_cards: 从特定仪表板提取所有卡片
• execute_query: 对任何连接的数据库执行自定义SQL查询

配置

该服务器支持两种认证方法：

选项1：用户名和密码认证

# 必需
METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your_email@example.com
METABASE_PASSWORD=your_password

# 可选
LOG_LEVEL=info # 选项：debug, info, warn, error, fatal

选项2：API密钥认证（推荐用于生产环境）

# 必需
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_api_key

# 可选
LOG_LEVEL=info # 选项：debug, info, warn, error, fatal

您可以直接设置这些环境变量，或使用带有dotenv的.env文件。

安装

先决条件

• Node.js 18.0.0 或更高版本
• 具有适当凭据的活动Metabase实例

开发设置

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务器
npm start

# 开发时自动重建
npm run watch

Claude Desktop 集成

要在Claude Desktop中使用，请添加此服务器配置：

MacOS: 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: 编辑 %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "/absolute/path/to/metabase-mcp-server/build/index.js",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USER_EMAIL": "your_email@example.com",
        "METABASE_PASSWORD": "your_password"
        // 或者，也可以使用API密钥认证
        // "METABASE_API_KEY": "your_api_key"
      }
    }
  }
}

或者，您可以使用Smithery托管版本，通过npx和JSON配置：

API密钥认证：

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@hyeongjun-dev/metabase-mcp-server",
        "--config",
        "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"your_api_key\",\"metabasePassword\":\"\",\"metabaseUserEmail\":\"\"}"
      ]
    }
  }
}

用户名和密码认证：

{
  "mcpServers": {
    "metabase-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@hyeongjun-dev/metabase-mcp-server",
        "--config",
        "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"\",\"metabasePassword\":\"your_password\",\"metabaseUserEmail\":\"your_email@example.com\"}"
      ]
    }
  }
}

调试

由于MCP服务器通过stdio通信，可以使用MCP Inspector进行调试：

npm run inspector

Inspector将提供一个基于浏览器的界面来监控请求和响应。

Docker 支持

有一个Docker镜像可用于容器化部署：

# 构建Docker镜像
docker build -t metabase-mcp-server .

# 使用环境变量运行容器
docker run -e METABASE_URL=https://your-metabase.com \
           -e METABASE_API_KEY=your_api_key \
           metabase-mcp-server

安全注意事项

• 我们建议在生产环境中使用API密钥认证
• 保持您的API密钥和凭据安全
• 考虑使用Docker Secrets或环境变量而不是硬编码凭据
• 应用适当的网络安全措施以限制对您的Metabase实例的访问

贡献

欢迎贡献！请随时提交Pull Request。