元数据库-MCP

Name: 元数据库-MCP
Author: jerichosequitin

作者：jerichosequitin28 星标更新：2025-11-10

安装使用来源：spider==github.com

项目介绍

Metabase MCP 服务器

版本: 1.0.1

作者: Jericho Sequitin (@jerichosequitin)

这是一个高性能的模型上下文协议服务器，用于与Metabase分析平台集成AI。它具有智能缓存、响应优化和全面的数据访问工具。

作为MCP捆绑包（MCPB）提供给Claude桌面用户。

安装选项

选项1：MCP捆绑包（推荐给Claude桌面用户）

从发布页面下载metabase-mcp.mcpb
使用Claude桌面打开.mcpb文件进行安装
在Claude桌面扩展设置中配置您的Metabase凭据：
- Metabase URL（必需）
- 认证：选择API密钥或电子邮件/密码
- 导出目录：自定义文件保存位置（默认为Downloads/Metabase）
- 可选：日志级别、缓存TTL和请求超时设置

MCP捆绑包安装的好处

单击安装：无需手动配置文件或命令行设置
自动更新：Claude桌面管理捆绑包更新
用户友好的设置：通过Claude桌面UI进行配置
无缝集成：工具自动在对话中可用

选项2：手动安装

按照下面本地开发设置部分中的标准MCP服务器安装过程操作。

主要特性

高性能：通过响应优化减少高达90%的令牌
统一命令：list、retrieve、search、execute和export工具
智能缓存：多层缓存，可配置TTL
双认证：API密钥或电子邮件/密码认证
大数据导出：导出多达1M行的数据，支持CSV、JSON和XLSX格式
可配置导出目录：自定义文件保存位置

可用工具

服务器提供了以下优化工具供AI助手使用：

统一核心工具

list：获取单一资源类型的所有记录，具有高度优化的响应
- 支持：cards、dashboards、tables、databases、collections
- 仅返回浏览高效的必要标识字段
- 分页支持：对于超过令牌限制的大数据集（偏移量/限制参数）
- 智能缓存及性能指标
retrieve：根据ID获取特定项目的详细信息
- 支持：card、dashboard、table、database、collection、field
- 具有控制批次大小的并发处理
- 响应激进优化（75-90%令牌减少）
- 表分页：对于超过25k令牌限制的大数据库
search：使用原生搜索API跨所有Metabase项目进行统一搜索
- 支持所有模型类型，带有高级过滤
- 按名称、ID、内容或数据库搜索
- 包括仪表板问题和原生查询搜索

查询执行工具

execute：统一命令用于执行SQL查询或保存卡片（2K行限制）
- SQL模式：使用数据库ID和查询参数执行自定义SQL查询
- 卡片模式：使用卡片ID参数执行保存的Metabase卡片，并可选过滤
- 卡片参数：使用card_parameters数组过滤卡片结果
- 增强了适当的LIMIT子句处理和参数验证
- 智能模式检测及严格的参数验证
export：统一命令用于导出大数据集（最多1M行）
- SQL模式：使用数据库ID和查询参数导出自定义SQL查询结果
- 卡片模式：使用卡片ID参数导出保存的Metabase卡片结果，并可选过滤
- 卡片参数：在导出前使用card_parameters数组过滤卡片结果
- 支持CSV、JSON和XLSX格式，不区分大小写的格式处理
- 自动保存到可配置目录（默认为~/Downloads/Metabase/）

实用工具

clear_cache：具有细粒度控制的内部缓存清除
- 支持针对个别项目和列表的模型特定缓存清除
- 单个项目缓存：cards、dashboards、tables、databases、collections、fields
- 列表缓存：cards-list、dashboards-list、tables-list、databases-list、collections-list
- 批量操作：all、all-individual、all-lists

快速开始示例

// 列出所有卡片
list({ model: "cards" })

// 获取详细的卡片信息
retrieve({ model: "card", ids: [1, 2, -3] })

// 搜索仪表板
search({ query: "sales", models: ["dashboard"] })

// 执行SQL查询
execute({
  database_id: 1,
  query: "SELECT * FROM users LIMIT 100"
})

// 导出大数据集
export({
  database_id: 1,
  query: "SELECT * FROM large_table",
  format: "csv"
})

配置

认证选项

API密钥（推荐）：

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

电子邮件/密码：

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

可选设置：

EXPORT_DIRECTORY=~/Downloads/Metabase  # 或 ${DOWNLOADS}/Metabase
LOG_LEVEL=info

手动安装（开发者）

需求

Node.js 18.0.0或更高版本
活跃的Metabase实例

设置

# 克隆并构建
git clone https://github.com/jerichosequitin/metabase-mcp.git
cd metabase-mcp
npm install
npm run build

环境配置

创建一个.env文件：

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

# 选择认证方法
METABASE_API_KEY=your_api_key  # 推荐
# 或
# METABASE_USER_EMAIL=your_email@example.com
# METABASE_PASSWORD=your_password

# 可选
EXPORT_DIRECTORY=~/Downloads/Metabase  # 或 ${DOWNLOADS}/Metabase
LOG_LEVEL=info
CACHE_TTL_MS=600000 # 默认10分钟
REQUEST_TIMEOUT_MS=600000 # 默认10分钟

Claude桌面集成

要与Claude桌面集成，您需要在Claude的配置文件中配置MCP服务器。

配置文件位置：

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

本地开发：

{
  "mcpServers": {
    "metabase-mcp": {
      "command": "/Users/your-username/path/to/metabase-mcp/build/src/index.js",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "info",
        "CACHE_TTL_MS": "600000",
        "EXPORT_DIRECTORY": "/path/to/your/export/directory"
      }
    }
  }
}

重要提示：

使用绝对路径进行本地开发（例如，/Users/username/Documents/metabase-mcp/build/src/index.js）
**替换your-username**为您实际的用户名
**替换path/to/metabase-mcp**为您克隆的仓库的实际路径
无需手动运行服务器—Claude桌面会自动调用并管理MCP服务器通过STDIO
切勿将真实凭证提交到版本控制
更改配置后重启Claude桌面

故障排除：

确保build/src/index.js的路径正确且文件存在
验证您的Metabase凭据是否有效
查看Claude桌面的日志以检查连接错误
确保服务器成功构建npm run build

高级用法

卡片参数

执行带有过滤器的保存卡片时，使用card_parameters数组：

execute({
  card_id: 42,
  card_parameters: [
    {
      "id": "param-uuid",
      "slug": "start_date",
      "target": ["dimension", ["template-tag", "start_date"]],
      "type": "date/all-options",
      "value": "2024-01-01~2024-12-31"
    }
  ]
})

通过检索卡片详情获取参数结构。

分页

// 带分页的列表
list({ model: "cards", limit: 100, offset: 0 })

// 大型数据库表
retrieve({ model: "database", ids: [1], table_limit: 20 })

调试

使用MCP Inspector进行开发：

npm run inspector

Docker支持

# 构建和测试
docker build -t metabase-mcp .
docker run -e METABASE_URL=https://metabase.example.com \
           -e METABASE_API_KEY=your_api_key \
           metabase-mcp

注意：Docker主要用于开发/测试。

开发

测试

# 运行测试
npm test

# 覆盖报告
npm run test:coverage

# 开发工具
npm run inspector  # MCP Inspector用于调试

构建MCPB包

# 为分发构建
npm run mcpb:build

生成metabase-mcp-{version}.mcpb（例如，metabase-m-1.0.1.mcpb），准备上传到GitHub Releases。

安全考虑

API密钥认证：生产环境推荐使用
凭据安全：基于环境变量的配置
Docker密钥：支持Docker密钥和环境变量
网络安全：应用适当的网络安全措施
速率限制：内置请求速率限制和超时处理

许可证

本项目采用MIT许可证。