元数据库MCP服务器

📊 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 服务器的实际操作：

<img src="https://i.ytimg.com/vi/1-86KuNwbdE/maxresdefault.jpg">

---

📐 架构图

---

🚀 开始使用

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

请遵循官方的 Metabase 安装指南：Metabase 文档

2. 安装 uv 包管理器

安装 uv，它包括 Python 和包管理：

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 (通过 Scoop)
scoop install uv

# Windows (通过 Chocolatey)
choco install uv

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

3. 克隆或下载仓库

您需要将此工具放到您的计算机上。您可以手动下载它，也可以使用 Git。 打开您的计算机的终端（Mac）或命令提示符（Windows）。 导航到您解压文件或想要克隆项目的文件夹：

# 示例（替换为您实际的路径）：
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/codewalnut/metabase-mcp-server.git
cd metabase-mcp-server

4. 安装依赖项

此命令将自动：

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

uv sync

5. 配置您的凭据

您有三种方法来配置 Metabase 凭据用于 MCP 服务器：

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

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

选项 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 DEBUG

选项 3: 在 MCP 客户端配置中使用环境变量 直接在您的 MCP 客户端中配置，而不使用 .env 文件（参见下面的示例）。

{
  "mcpServers": {
    "metabase": {
      "type": "stdio"
      "command": "uv",
      "args": ["run", "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=DEBUG
      }
    }
  }
}

6. 连接到您的 MCP 客户端

选择您喜欢的 MCP 客户端，如 Claude Desktop 应用程序、Claude Code、Cursor、Windsurf 等，并在各自的配置文件中添加 Metabase MCP 服务器。所有 MCP 客户端都遵循类似的配置模式。

配置示例

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

Windows:

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

Mac:

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "/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	传输协议	streamable-http	stdio, streamable-http
HOST	HTTP 传输主机	localhost	0.0.0.0, 127.0.0.1
PORT	HTTP 传输端口	3200	8080, 9000
LOG_LEVEL	日志级别	INFO	DEBUG, WARNING, ERROR

命令行参数

参数	描述	默认值
--metabase-url	Metabase 实例 URL	必需
--metabase-api-key	Metabase API 密钥	必需
--transport	传输协议	streamable-http
--host	HTTP 传输主机	localhost
--port	HTTP 传输端口	3200
--log-level	日志详细程度	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 密钥”标签页
5. 点击“创建 API 密钥”
6. 给您的密钥一个描述性的名称（例如，“MCP 服务器密钥”）
7. 复制生成的密钥（以 mb_ 开头）

⚠️ 重要： 安全存储您的 API 密钥，切勿将其提交到版本控制。该密钥提供了对您的 Metabase 实例的完全访问权限。

---

📂 DXT 文件支持

您不再需要经历克隆仓库和设置环境的步骤。只需按照以下步骤在您的 Cloude Desktop App 中安装 Metabase MCP 服务器：

1. 下载 DXT 文件
   查看下方链接以直接下载最新的 DXT 文件：
   下载 DXT 文件

2. 打开 Cloude Desktop App
   拥有文件后，在您的系统上打开 Cloude Desktop App。

3. 导航到扩展设置
   在 Cloude Desktop App 中：

   • 转到 文件 → 设置 → 扩展
   • 然后点击 高级设置。

4. 选择 DXT 文件
   在 高级设置 部分，点击 选择文件，选择下载的 DXT 文件。

5. 输入所需详情
   选择 DXT 文件 后，会出现一个提示，要求您填写所需详情：

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

6. 完成设置
   输入必要详情后，点击 保存 应用配置。

就这样！Metabase MCP 服务器 现已在您的 Cloude Desktop App 中安装并准备好使用。

如何创建自己的 DXT 文件

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

🚀 远程部署

为了生产使用或团队协作，您可以远程部署 Metabase MCP 服务器。我们在 Codewalnut 内部使用这种方法。

Docker 部署

我们包含了 Docker 配置文件，以便远程部署变得简单。

使用 Docker 快速启动

# 构建 Docker 镜像
docker build -t metabase-mcp-server .

# 使用环境变量运行
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=DEBUG
    restart: unless-stopped

连接到远程 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 团队提供部署和咨询服务。联系我们