Metabase MCP Server

Metabase MCP 服务

作者：Hyeongjun Yu (@hyeongjun-dev)

一个将 AI 助手与 Metabase 分析平台集成的 Model Context Protocol 服务。

概述

这个基于 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：用户名和密码身份验证

# Required
METABASE_URL=https://your-metabase-instance.com
[email protected]
METABASE_PASSWORD=your_password

# Optional
LOG_LEVEL=info # Options: debug, info, warn, error, fatal

选项 2：API 密钥身份验证（生产环境推荐）

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

# Optional
LOG_LEVEL=info # Options: debug, info, warn, error, fatal

你可以直接设置这些环境变量，也可以使用 dotenv 配合 .env 文件。

安装

前置条件

• Node.js 18.0.0 或更高版本
• 正在运行且具有适当凭据的 Metabase 实例

开发环境设置

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# For development with auto-rebuild
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": "[email protected]",
        "METABASE_PASSWORD": "your_password"
        // Or alternatively, use API key authentication
        // "METABASE_API_KEY": "your_api_key"
      }
    }
  }
}

或者，你也可以通过 npx 使用 Smithery 托管版本，并采用 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\":\"[email protected]\"}"
      ]
    }
  }
}

调试

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

npm run inspector

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

Docker 支持

提供了 Docker 镜像，可用于容器化部署：

# Build the Docker image
docker build -t metabase-mcp-server .

# Run the container with environment variables
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。