元数据库服务器MCP服务器
用于元数据库集成的模型上下文协议服务器。
这是一个基于类型脚本的MCP服务器，实现与Metabase API的集成。它允许AI助手与Metabase交互，提供以下访问：
- 仪表板、问题/卡片和数据库作为资源
- 用于列出和执行元数据库查询的工具
- 能够查看元数据库数据并与之交互
特性
资源
- 通过以下方式列出和访问元数据库资源
metabase://URI - 访问仪表板、卡片/问题和数据库
- 用于结构化数据访问的JSON内容类型
工具
list_dashboards-列出元数据库中的所有仪表板list_cards-在元数据库中列出所有问题/卡片list_databases-列出元数据库中的所有数据库execute_card-执行元数据库问题/卡片并获得结果get_dashboard_cards-在仪表板中获取所有卡片execute_query-对元数据库执行SQL查询
配置
在运行服务器之前，您需要设置用于身份验证的环境变量。服务器支持两种方法：
- API密钥（首选）：
- METABASE_URL：元数据库实例的URL（例如。， https://your-metabase-instance.com). - METABASE_API_KEY：您的Metabase API密钥。
- 用户名/密码（回退）：
- 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密钥认证进行测试
- 设置
METABASE_URL和METABASE_API_KEY带有Metabase实例URL和有效API密钥的环境变量。 - 确保
METABASE_USERNAME和METABASE_PASSWORD取消设置或保留它们，因为API键应优先。 - 启动服务器：
npm run build && node build/index.js（或使用您选择的方法运行服务器，如通过Claude Desktop配置）。 - 检查服务器日志。您应该看到一条消息，指示它正在使用API密钥身份验证（例如，“使用Metabase API密钥进行身份验证”）。
- 使用MCP客户端或MCP检查器，尝试调用一个工具，例如，
tools/call随着{"name": "list_dashboards"}. - 验证工具调用是否成功，以及您是否收到了预期的数据。
2.使用用户名/密码验证进行测试（回退）
- 确保
METABASE_API_KEY环境变量未设置。 - 集
METABASE_URL,METABASE_USERNAME，以及METABASE_PASSWORD具有Metabase实例的有效凭据。 - 启动服务器。
- 检查服务器日志。您应该看到一条消息，指示它正在使用用户名/密码身份验证（例如，“使用元数据库用户名/密码进行身份验证。”然后是“使用用户名/口令使用元数据库进行身份验证…”）。
- 使用MCP客户端或MCP检查器，尝试调用
list_dashboards工具。 - 验证工具调用是否成功。
3.测试身份验证失败
- 无效的API密钥：
1. 集 METABASE_URL 和一个无效 METABASE_API_KEY.确保 METABASE_USERNAME 和 METABASE_PASSWORD 变量未设置。 1. 启动服务器。 1. 尝试调用工具（例如。， list_dashboards).工具调用应该失败，并且服务器日志可能指示Metabase的身份验证错误（例如，“Metabase API错误：无效的X-API-Key”）。
- 无效的用户名/密码：
1. 确保 METABASE_API_KEY 未设置。集 METABASE_URL 无效 METABASE_USERNAME/METABASE_PASSWORD. 1. 启动服务器。 1. 尝试调用工具。由于会话身份验证失败，工具调用应失败。服务器日志可能显示“身份验证失败”或“无法通过元数据库进行身份验证”。
- 缺少凭据：
1. 取消设置 METABASE_API_KEY, METABASE_USERNAME，以及 METABASE_PASSWORD.仅设置 METABASE_URL. 1. 尝试启动服务器。 1. 服务器应无法启动并记录一条错误消息，说明需要身份验证凭据（API密钥或用户名/密码）（例如，“需要（METABASE_URL和METABASE_API_key）或（METAABASE_URL、METAABASE-username和METAABASE_password）环境变量”）。