📊 Metabase MCP Server

📊 Metabase MCP 服务

📚 目录

1. 这款工具是什么？
2. 视频演示
3. 架构图
4. 快速开始
   • 设置 Metabase
   • 安装 uv 包管理器
   • 克隆或下载仓库
   • 安装依赖项
   • 配置凭据
   • 连接到 MCP 客户端
5. 配置选项
6. 获取 Metabase API 密钥
7. DXT 文件支持
8. 如何创建自己的 DXT 文件
9. 远程部署
10. 使用 MCP Inspector 调试
11. 可用工具
12. 可试用的示例提示词
13. 联系我们
14. 许可证

---

😊 这款工具是什么？

Metabase MCP 服务是一个后端集成层，通过模型上下文协议（MCP）将你的 Metabase 实例与 AI 助手连接起来。这让业务负责人、产品经理和分析师能够通过任何 MCP 客户端（例如 Claude Desktop），使用自然语言与仪表板和图表等商业智能资源进行交互。

无需在菜单中逐项查找或手动编写 SQL 查询，你可以：

• 提出问题并立即获得洞察。
• 通过描述需求来生成仪表板和图表。
• 通过简单的指令管理用户访问权限和数据库连接。

这个项目让 Metabase 不再只是一个仪表板工具，而是一个能通过对话交互的智能业务助手。

---

🎥 视频演示

观看此视频，了解 Metabase MCP 服务的实际运行情况：

---

📐 架构图

---

🚀 快速开始

1. 设置 Metabase（如果你尚未设置）

请按照 Metabase 官方安装指南操作：Metabase 文档

2. 安装 uv 包管理器

安装包含 Python 和包管理功能的 uv：

Windows：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

也可以通过包管理器安装：

# macOS
brew install uv

# Windows (via Scoop)
scoop install uv

# Windows (via Chocolatey)
choco install uv

如需了解更多关于 uv 安装和使用的信息，请访问官方文档：https://docs.astral.sh/uv/getting-started/installation/

3. 克隆或下载仓库

你需要将此工具放到电脑上。你可以手动下载，也可以使用 Git。 打开电脑上的 Terminal（Mac）或 Command Prompt（Windows）。 进入解压文件或准备克隆项目的文件夹：

# Example (replace with your actual path):
cd ~/Downloads/metabase-mcp-server-dev

选项 1：下载 ZIP

1. 前往 GitHub 仓库
2. 点击绿色的 "Code" 按钮
3. 选择 "Download ZIP"
4. 将下载的文件解压到 Documents 等文件夹中

选项 2：使用 Git 如果你熟悉 Git，请在终端中运行：

git clone https://github.com/CW-Codewalnut/Metabase-MCP-Server.git
cd Metabase-MCP-Server

4. 安装依赖项

此命令会自动：

• 安装所需的 Python 版本（如果尚未安装）
• 为项目创建虚拟环境
• 安装所有必需的软件包和依赖项

uv sync

5. 配置凭据

你可以通过以下三种方式为 MCP 服务配置 Metabase 凭据：

选项 1：使用 .env 文件（推荐） 在项目根目录中创建一个 .env 文件：

METABASE_URL=http://localhost:3000
METABASE_API_KEY=mb_xxx_your_key
PORT=3200
HOST=localhost
TRANSPORT=streamable-http
LOG_LEVEL=INFO

选项 2：使用命令行参数 通过命令行直接传递配置：

uv run src/metabase_mcp_server.py --metabase-url http://localhost:3000 --metabase-api-key "YOUR_API_KEY" --port 3200 --host localhost --transport streamable-http --log-level INFO

选项 3：在 MCP 客户端配置中使用环境变量 无需 .env 文件，直接在 MCP 客户端中配置（参见下方示例）。

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"
      ],
      "env": {
        "METABASE_URL": "http://localhost:3000",
        "METABASE_API_KEY": "mb_xxx_your_key",
        "PORT": 3200,
        "HOST": "localhost",
        "TRANSPORT": "streamable-http",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

6. 连接到 MCP 客户端

选择你偏好的 MCP 客户端，例如 Claude 桌面应用、Claude Code、Cursor、Windsurf 等，并在各自的配置文件中添加 Metabase MCP 服务。所有 MCP 客户端都遵循类似的配置模式。

配置示例

对于 stdio 传输（本地 MCP 服务推荐）：

Windows：

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\Projects\\metabase-mcp-server\\src\\metabase_mcp_server.py"
      ]
    }
  }
}

Mac：

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "/Users/YourName/Projects/metabase-mcp-server/.venv/bin/python",
      "args": [
        "/Users/YourName/Projects/metabase-mcp-server/src/metabase_mcp_server.py"
      ]
    }
  }
}

主要区别：

• Windows 路径使用反斜杠 \\
• macOS/Linux 路径使用正斜杠 /
• 请根据你的操作系统使用正确的格式，以免出错

重要说明：

• 将 FULL_PATH 替换为项目目录的实际绝对路径
• 保存配置更改后，重启 MCP 客户端以应用新设置
• 若要在 Cursor 中使用项目专属工具，请在项目目录中创建 .cursor/mcp.json 文件
• 若要在 Cursor 中使用全局工具，请在主目录中创建 ~/.cursor/mcp.json 文件

对于 streamable-http 传输（远程 MCP 服务推荐）：

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://localhost:3200/mcp/"
    }
  }
}

兼容的 MCP 客户端

点击任意客户端，访问其官方 MCP 配置文档：

客户端	官方 MCP 文档
	Anthropic 的 Claude Desktop 官方 MCP 指南
	Claude Code 官方 MCP 配置文档
	Cursor 官方 MCP 配置指南
	Windsurf 官方 MCP 配置文档
	Cline 官方 MCP 快速入门指南
	VS Code Copilot MCP 服务配置指南

添加配置后，MCP 服务应该会显示在 MCP 客户端中。

---

🔧 配置选项

Metabase MCP 服务支持通过环境变量、命令行参数或两者组合进行灵活配置。

环境变量

变量	描述	默认值	示例
METABASE_URL	你的 Metabase 实例 URL	必填	http://127.0.0.1:3000
METABASE_API_KEY	你的 Metabase API 密钥	必填	mb_xxx_your_api_key
TRANSPORT	传输协议	stdio	stdio、sse、streamable-http
HOST	HTTP 传输的主机	localhost	0.0.0.0、127.0.0.1
PORT	HTTP 传输的端口	3200	8080、9000
LOG_LEVEL	日志级别	INFO	DEBUG、INFO、WARNING、ERROR

命令行参数

参数	描述	选项	默认值
--metabase-url	Metabase 实例 URL	任意 Metabase URL	必填
--metabase-api-key	Metabase API 密钥	mb_... 密钥	必填
--transport	传输协议	stdio、sse、streamable-http	stdio
--host	HTTP 传输的主机	任意主机或 IP	localhost
--port	HTTP 传输的端口	任意端口号	3200
--log-level	日志详细程度	DEBUG、INFO、WARNING、ERROR	INFO

传输协议

协议	描述	使用场景
stdio	标准输入/输出通信	最适合本地集成（Claude Desktop、Cursor 等）
streamable-http	基于 HTTP 的流式传输协议	适用于远程部署和基于 Web 的集成
sse	基于 HTTP 的服务器发送事件	⚠️ 已弃用 — 不建议用于新配置

配置优先级

配置值按以下优先级顺序应用（从高到低）：

1. 命令行参数（覆盖所有其他设置）
2. 环境变量（覆盖默认值）
3. 默认值

完整命令示例

uv run src/metabase_mcp_server.py --transport streamable-http --host localhost --port 3200 --metabase-url http://127.0.0.1:3000 --metabase-api-key mb_xxx_your_key

注意： 运行服务时无需传入每个参数。但必须提供 Metabase URL 和 API 密钥。未指定的参数将使用上文所示的默认值。

---

🔑 获取 Metabase API 密钥

获取 Metabase API 密钥：

1. 登录你的 Metabase 实例
2. 点击个人资料图片（右上角）
3. 选择“账户设置”
4. 转到“API Keys”选项卡
5. 点击“创建 API 密钥”
6. 为密钥取一个描述性名称（例如，“MCP Server Key”）
7. 复制生成的密钥（以 mb_ 开头）

⚠️ 重要： 请妥善保管 API 密钥，切勿将其提交到版本控制中。该密钥可完整访问你的 Metabase 实例。

---

📂 DXT 文件支持

您无需再克隆仓库和配置环境，只需按照以下步骤，即可在 Claude 桌面应用中安装 Metabase MCP 服务：

1. 下载 DXT 文件
   点击下方链接，直接下载最新的 DXT 文件：
   下载 DXT 文件

2. 打开 Claude 桌面应用
   下载文件后，在您的系统上打开 Claude 桌面应用。

3. 进入扩展设置
   在 Claude 桌面应用中：

   • 前往 Files → Settings → Extensions
   • 然后点击 Advanced Settings。

4. 选择 DXT 文件
   在 Advanced Settings 部分，点击 Choose File，然后选择已下载的 DXT 文件。

5. 填写所需信息
   选择 DXT 文件后，会出现提示，要求您填写所需信息：

   • Metabase URL：输入您的 Metabase 服务 URL。
   • API Key：添加相应的 API 密钥进行身份验证。

6. 完成设置
   填写所需信息后，点击 Save 应用配置。

就这样！Metabase MCP 服务现在已安装完毕，可在您的 Claude 桌面应用中使用。

如何创建自己的 DXT 文件

如果您想创建自己的 DXT 文件，请参阅官方指南：
创建自己的 DXT 文件

🚀 远程部署

对于生产环境或团队协作，您可以远程部署 Metabase MCP 服务。我们在 Codewalnut 内部也采用这种方式。

Docker 部署

我们提供了 Docker 配置文件，让远程部署更加简单。

使用 Docker 快速开始

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

# Run with environment variables
docker run -d \
  -p 3200:3200 \
  -e METABASE_URL="http://your-metabase-instance.com" \
  -e METABASE_API_KEY="mb_xxx_your_api_key" \
  metabase-mcp-server

Docker Compose（推荐）

version: "3.8"
services:
  metabase-mcp:
    build: .
    ports:
      - "3200:3200"
    environment:
      - METABASE_URL=http://your-metabase-instance.com
      - METABASE_API_KEY=mb_xxx_your_api_key
      ##- PORT=3200
      ##- HOST=localhost
      ##- TRANSPORT=streamable-http
      ##- LOG_LEVEL=INFO
    restart: unless-stopped

默认情况下，远程 HTTP/SSE 传输方式为只读。仅当服务部署在可信访问控制之后，且配置的 Metabase API 密钥获准执行相应更改时，才将匹配的 ALLOW_* 环境变量设为 true： ALLOW_WRITE_TOOLS、ALLOW_ADMIN_TOOLS 和 ALLOW_SQL_TOOL。

连接远程 MCP 服务

部署完成后，配置您的 MCP 客户端以连接远程服务：

{
  "mcpServers": {
    "metabase": {
      "type": "streamable-http",
      "url": "http://server-ip:3200/mcp/"
    }
  }
}

部署选项

• 云服务提供商： AWS ECS、Google Cloud Run、Azure Container Instances
• VPS/专用服务器： DigitalOcean、Linode、Vultr
• 容器平台： Kubernetes、Docker Swarm
• 平台即服务： Railway、Render、Fly.io

安全注意事项

• 在生产环境中使用 HTTPS
• 配置适当的防火墙规则
• 对敏感业务数据考虑使用 VPN 访问
• 定期轮换 API 密钥
• 监控访问日志

需要部署方面的帮助？

CodeWalnut 团队提供部署和咨询服务。如需企业级设置和支持，请联系我们。

---

🔍 使用 MCP Inspector 调试

您可以使用官方 MCP Inspector 工具调试和测试 Metabase MCP 服务的设置。

前置条件

如果您尚未安装 Node.js，请先安装：

• 下载地址： nodejs.org

• 或通过包管理器安装：

  # macOS
  brew install node
  
  # Windows (via Chocolatey)
  choco install nodejs
  
  # Windows (via Scoop)
  scoop install nodejs
  

安装并运行 MCP Inspector

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your Metabase MCP Server
npx @modelcontextprotocol/inspector uv run FULL_PATH/metabase-mcp-server/src/metabase_mcp_server.py

使用 MCP Inspector

MCP Inspector 提供：

• 实时工具测试 - 直接从 Web 界面执行 MCP 工具
• 请求/响应监控 - 查看发送和接收的数据
• 错误调试 - 快速定位配置或 API 问题
• 架构验证 - 确认工具定义正确

启动后，在浏览器中打开 http://localhost:5173，即可访问 Inspector 界面。

常见调试场景

• 连接问题 - 检查您的 Metabase URL 和 API 密钥
• 权限错误 - 检查您的 API 密钥是否具有所需权限

---

🔧 可用工具

功能	描述
集合操作
get_metabase_collection	按 ID 获取集合
create_metabase_collection	创建新集合
update_metabase_collection	更新集合元数据
delete_metabase_collection	删除集合
图表（卡片）操作
get_metabase_cards	列出所有图表
get_card_query_results	获取图表查询结果
create_metabase_card	创建新图表
update_metabase_card	更新现有图表
delete_metabase_card	删除图表
仪表板操作
get_metabase_dashboards	列出所有仪表板
get_dashboard_by_id	按 ID 获取仪表板
get_dashboard_cards	获取仪表板中的卡片
get_dashboard_items	获取所有仪表板项目
create_metabase_dashboard	创建仪表板
update_metabase_dashboard	更新仪表板
delete_metabase_dashboard	删除仪表板
copy_metabase_dashboard	创建现有仪表板的副本
数据库操作
get_metabase_databases	列出数据库
create_metabase_database	创建新的数据库连接
update_metabase_database	更新数据库连接
delete_metabase_database	删除数据库连接
用户操作
get_metabase_users	列出所有用户
get_metabase_current_user	获取当前用户详情
create_metabase_user	创建新用户
update_metabase_user	更新用户信息
delete_metabase_user	删除用户
群组操作
get_metabase_groups	列出用户群组
create_metabase_group	创建用户群组
delete_metabase_group	删除用户群组
SQL 操作
execute_sql_query	执行原生 SQL 查询

---

🧪 可尝试的示例提示词

• 创建一个名为 'Flight Overview' 的仪表板，其中包含一个按目的地城市显示航班数量的柱状图。
• 运行 SQL：SELECT origin, destination, COUNT(*) FROM flights GROUP BY origin, destination LIMIT 10。
• 创建一张卡片，显示上个月按地区分组的预订总数。
• 删除名为 'Abandoned Queries' 的图表。
• 更新仪表板 'Sales KPIs'，添加一张新的收入卡片。
• 显示 'Admin' 群组中的所有用户。
• 创建一个名为 'Finance Analysts' 的新群组。
• 连接到 Supabase 数据库并列出所有表。

---

🌐 联系我们

通过我们的社区渠道保持联系并获取支持：

🏢 官方链接

• 🌍 网站： codewalnut.com
• 📧 电子邮件： [email protected]
• 📖 博客：
  • insights： codewalnut.com/insights
  • learn： codewalnut.com/learn

📱 社交媒体

• 💼 LinkedIn： CodeWalnut
• 📺 YouTube： CodeWalnut 频道
• 🐦 Twitter/X： @codewalnut
• 📷 Instagram： @codewalnut

💬 社区支持

• 📧 新闻简报： 订阅 CodeWalnut 新闻简报（向下滚动以查找邮件订阅选项）
• 🐙 GitHub： codewalnut

🤝 专业服务

• 咨询： 定制 Metabase 集成和 AI 解决方案
• 培训： MCP 和商业智能工作坊
• 支持： 企业级支持与维护

📢 关注我们，获取有关全新 MCP 服务、AI 集成和商业智能工具的最新消息！

---

📜 许可证

本项目采用 Apache License 2.0 许可。

你可以在 LICENSE 文件中查看完整的许可证文本。

---