AI导哈

Metabase集成服务器

一个基于TypeScript的MCP服务器，实现与Metabase API的集成，允许AI助手访问和交互Metabase数据。

  • by imlewc
  • JavaScript
  • 本地部署
  • 151 星标
  • 更新于
在 GitHub 查看 imlewc/metabase-server

使用说明

元数据库服务器MCP服务器

用于元数据库集成的模型上下文协议服务器。

这是一个基于类型脚本的MCP服务器，实现与Metabase API的集成。它允许AI助手与Metabase交互，提供以下访问：

  • 仪表板、问题/卡片和数据库作为资源
  • 用于列出和执行元数据库查询的工具
  • 能够查看元数据库数据并与之交互

特性

资源

  • 通过以下方式列出和访问元数据库资源 metabase:// URI
  • 访问仪表板、卡片/问题和数据库
  • 用于结构化数据访问的JSON内容类型

工具

  • list_dashboards -列出元数据库中的所有仪表板
  • list_cards -在元数据库中列出所有问题/卡片
  • list_databases -列出元数据库中的所有数据库
  • execute_card -执行元数据库问题/卡片并获得结果
  • get_dashboard_cards -在仪表板中获取所有卡片
  • execute_query -对元数据库执行SQL查询

配置

在运行服务器之前，您需要设置用于身份验证的环境变量。服务器支持两种方法：

  1. API密钥（首选）：

    • METABASE_URL：元数据库实例的URL（例如。， https://your-metabase-instance.com).
    • METABASE_API_KEY：您的Metabase API密钥。

  2. 用户名/密码（回退）：

    • METABASE_URL：元数据库实例的URL。
    • METABASE_USERNAME：您的元数据库用户名。
    • METABASE_PASSWORD：您的元数据库密码。

服务器将首先检查 METABASE_API_KEY。如果已设置，则将使用API密钥身份验证。如果 METABASE_API_KEY 如果未设置，服务器将恢复使用 METABASE_USERNAME 和 METABASE_PASSWORD。您必须提供这些方法中至少一种的凭据。

示例设置：

使用API密钥：

# Required environment variables
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

或者，使用用户名/密码：

# Required environment variables
export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

您可以在shell配置文件中设置这些环境变量，也可以使用 .env 带有类似包的文件 dotenv.

发展

安装依赖项：

npm install

构建服务器：

npm run build

对于自动重建的开发：

npm run watch

安装

# Oneliner, suitable for CI environment
git clone https://github.com/imlewc/metabase-server.git && cd metabase-server && npm i && npm run build && npm link

要与Claude Desktop一起使用，请添加服务器配置：

在MacOS上： ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-server": {
      "command": "metabase-server",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        // Use API Key (preferred)
        "METABASE_API_KEY": "your_metabase_api_key"
        // Or Username/Password (if API Key is not set)
        // "METABASE_USERNAME": "your_username",
        // "METABASE_PASSWORD": "your_password"
      }
    }
  }
}

注意：如果你愿意，你也可以在系统中设置这些环境变量，而不是在配置文件中。

通过Smithery安装

通过以下方式自动安装Claude Desktop的元数据库服务器 铁匠铺:

npx -y @smithery/cli install @imlewc/metabase-server --client claude

通过Claude Code CLI安装

要为Claude Code CLI安装元数据库服务器，请执行以下操作：

claude mcp add metabase-server -s user \
  -e METABASE_URL="https://your-metabase-instance.com" \
  -e METABASE_USERNAME="your-email@example.com" \
  -e METABASE_PASSWORD="your-password" \
  -- npx -y @imlewc/metabase-server

或使用API密钥（首选）：

claude mcp add metabase-server -s user \
  -e METABASE_URL="https://your-metabase-instance.com" \
  -e METABASE_API_KEY="your-api-key" \
  -- npx -y @imlewc/metabase-server

配置将写入 ~/.claude.json:

{
  "mcpServers": {
    "metabase-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@imlewc/metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USERNAME": "your-email@example.com",
        "METABASE_PASSWORD": "your-password"
      }
    }
  }
}

故障排除

如果MCP服务器连接失败，请检查日志：

cat ~/.claude/debug/latest | grep -i metabase

常见问题：

  • 未配置环境变量("env": {} 为空）
  • URL格式无效（必须包括 https://)
  • 凭据错误

调试

由于MCP服务器通过stdio进行通信，调试可能具有挑战性。我们建议使用 MCP检查员，可作为包脚本使用：

npm run inspector

检查器将提供一个URL，用于访问浏览器中的调试工具。

测试

按照“配置”部分中的描述配置环境变量后，您可以手动测试服务器的身份验证。MCP检查员(npm run inspector)是向服务器发送请求的有用工具。

1.使用API密钥认证进行测试

  1. 设置 METABASE_URL 和 METABASE_API_KEY 带有Metabase实例URL和有效API密钥的环境变量。
  2. 确保 METABASE_USERNAME 和 METABASE_PASSWORD 取消设置或保留它们，因为API键应优先。
  3. 启动服务器： npm run build && node build/index.js （或使用您选择的方法运行服务器，如通过Claude Desktop配置）。
  4. 检查服务器日志。您应该看到一条消息，指示它正在使用API密钥身份验证（例如，“使用Metabase API密钥进行身份验证”）。
  5. 使用MCP客户端或MCP检查器，尝试调用一个工具，例如， tools/call 随着 {"name": "list_dashboards"}.
  6. 验证工具调用是否成功，以及您是否收到了预期的数据。

2.使用用户名/密码验证进行测试（回退）

  1. 确保 METABASE_API_KEY 环境变量未设置。
  2. 集 METABASE_URL, METABASE_USERNAME，以及 METABASE_PASSWORD 具有Metabase实例的有效凭据。
  3. 启动服务器。
  4. 检查服务器日志。您应该看到一条消息，指示它正在使用用户名/密码身份验证（例如，“使用元数据库用户名/密码进行身份验证。”然后是“使用用户名/口令使用元数据库进行身份验证…”）。
  5. 使用MCP客户端或MCP检查器，尝试调用 list_dashboards 工具。
  6. 验证工具调用是否成功。

3.测试身份验证失败

  • 无效的API密钥：
    1. 集 METABASE_URL 和一个无效 METABASE_API_KEY.确保 METABASE_USERNAME 和 METABASE_PASSWORD 变量未设置。
    2. 启动服务器。
    3. 尝试调用工具（例如。， list_dashboards).工具调用应该失败，并且服务器日志可能指示Metabase的身份验证错误（例如，“Metabase API错误：无效的X-API-Key”）。
  • 无效的用户名/密码：
    1. 确保 METABASE_API_KEY 未设置。集 METABASE_URL 无效 METABASE_USERNAME/METABASE_PASSWORD.
    2. 启动服务器。
    3. 尝试调用工具。由于会话身份验证失败，工具调用应失败。服务器日志可能显示“身份验证失败”或“无法通过元数据库进行身份验证”。
  • 缺少凭据：
    1. 取消设置 METABASE_API_KEY, METABASE_USERNAME，以及 METABASE_PASSWORD.仅设置 METABASE_URL.
    2. 尝试启动服务器。
    3. 服务器应无法启动并记录一条错误消息，说明需要身份验证凭据（API密钥或用户名/密码）（例如，“需要（METABASE_URL和METABASE_API_key）或（METAABASE_URL、METAABASE-username和METAABASE_password）环境变量”）。

相关 MCP