metabase-server MCP Server

这是一个用于与Metabase集成的Model Context Protocol服务器。

这是一个基于TypeScript的MCP服务器，实现了与Metabase API的集成。它允许AI助手与Metabase进行交互，提供以下资源的访问：

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

功能

资源

• 通过metabase://URI列表并访问Metabase资源
• 访问仪表板、卡片/问题和数据库
• 使用JSON内容类型访问结构化数据

工具

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

配置

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

1. API密钥（首选）：

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

2. 用户名/密码（备用）：

   • METABASE_URL：您的Metabase实例的URL。
   • METABASE_USERNAME：您的Metabase用户名。
   • METABASE_PASSWORD：您的Metabase密码。

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

示例配置：

使用API密钥：

# 必需的环境变量
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

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

# 必需的环境变量
export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

您可以在shell配置文件中设置这些环境变量，或使用dotenv包等工具的.env文件。

开发

安装依赖项：

npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

安装

# 适合CI环境的一行命令
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",
        // 使用API密钥（首选）
        "METABASE_API_KEY": "your_metabase_api_key"
        // 或者用户名/密码（如果未设置API密钥）
        // "METABASE_USERNAME": "your_username",
        // "METABASE_PASSWORD": "your_password"
      }
    }
  }
}

注意：您也可以在系统中设置这些环境变量，而不是在配置文件中设置它们。

通过Smithery安装

要通过Smithery自动安装metabase-server供Claude Desktop使用：

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

调试

由于MCP服务器通过标准I/O通信，调试可能会很困难。我们建议使用MCP Inspector，它作为一个包脚本可用：

npm run inspector

Inspector将提供一个URL，以便您可以在浏览器中访问调试工具。

测试

按照“配置”部分所述设置环境变量后，您可以手动测试服务器的身份验证。MCP Inspector（npm run inspector）是一个有用的工具，可以向服务器发送请求。

1. 使用API密钥身份验证测试

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

2. 使用用户名/密码身份验证（备用）测试

1. 确保METABASE_API_KEY环境变量未设置。
2. 设置METABASE_URL、METABASE_USERNAME和METABASE_PASSWORD，使用您的Metabase实例的有效凭据。
3. 启动服务器。
4. 检查服务器日志。您应该看到一条消息，表明它正在使用用户名/密码进行身份验证（例如，“使用Metabase用户名/密码进行身份验证。”，随后是“使用用户名/密码与Metabase进行身份验证...”）。
5. 使用MCP客户端或MCP Inspector，尝试调用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. 尝试调用一个工具。由于会话身份验证失败，工具调用应失败。服务器日志可能显示“身份验证失败”或“无法使用Metabase进行身份验证”。
• 缺少凭据：
  1. 取消设置METABASE_API_KEY、METABASE_USERNAME和METABASE_PASSWORD。仅设置METABASE_URL。
  2. 尝试启动服务器。
  3. 服务器应无法启动，并记录一条错误消息，指出需要身份验证凭据（API密钥或用户名/密码）（例如，“需要（METABASE_URL和METABASE_API_KEY）或（METABASE_URL、METABASE_USERNAME和METABASE_PASSWORD）环境变量”）。