Metabase MCP 服务器

📊 元数据库MCP服务器

📚 目录

1. 这个工具是关于什么的？
2. 视频演练
3. 架构图
4. 入门指南
   • 设置元数据库
   • 安装uv包管理器
   • 克隆或下载存储库
   • 安装依赖项
   • 配置您的凭据
   • 连接到您的MCP客户端
5. 配置选项
6. 获取您的Metabase API密钥
7. DXT文件支持
8. 如何创建自己的DXT文件
9. 远程部署
10. 使用MCP检查器进行调试
11. 可用工具
12. 示例提示尝试
13. 联系我们
14. 许可证

😊 这个工具是关于什么的？

元数据库MCP服务器 是一个后端集成层，连接您的 元数据库 实例与 AI助手 使用 模型上下文协议（MCP）。这允许业务领导者、产品经理和分析师使用以下工具与仪表板和图表等商业智能资产进行交互 自然语言--通过任何MCP客户端（例如Claude Desktop）。

您可以：

• 你可以问一个问题，并立即获得洞察力。
• 通过描述您想要的内容来生成仪表板和图表。
• 通过简单的说明管理用户访问和数据库连接。

这个项目使Metabase不仅仅是一个仪表板工具，而且是一个对话式的智能商务助理。

🎥 视频演练

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

📐 架构图

🚀 入门指南

1.设置元数据库（如果您还没有）

遵循Metabase官方安装指南： 元数据库文档

2.安装uv包管理器

安装 uv 包括Python和包管理：

窗户：

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

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

3.克隆或下载存储库

你需要把这个工具放到你的电脑上。您可以手动下载或使用Git。 打开计算机的终端（Mac）或命令提示符（Windows）。 导航到解压缩文件或要克隆项目的文件夹：

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

选项1：下载ZIP

1. 去 GitHub存储库

2. 点击绿色 “代码” 按钮

3. 选择 “下载ZIP”

4. 将下载的文件解压缩到类似您的位置 文件 文件夹

选项2：使用Git 如果您熟悉Git，请在终端中运行以下命令：

git clone git@github.com:amiralamox/mcp-metabase.git
cd mcp-metabase

4.安装依赖项

此命令将自动执行以下操作：

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

uv sync

5.配置您的凭据

您有三个选项来配置MCP服务器的元数据库凭据：

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

METABASE_URL=https://metabase.shippypro.admin
METABASE_API_KEY=YOUR_API_KEY
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客户端都遵循类似的配置模式。

配置示例

对于克劳德桌面/克劳德代码（推荐）：

{
  "mcpServers": {
    "metabase": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/metabase-mcp-server",
        "src/metabase_mcp_server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

替换 /path/to/your/metabase-mcp-server 使用项目目录的实际路径：

• 窗户： C:\\Users\\YourName\\Projects\\metabase-mcp-server
• macOS/Linux： /Users/YourName/Projects/metabase-mcp-server

对于其他MCP客户端（stdio传输）：

窗户：

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

雨衣：

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

主要区别：

• Windows使用 反斜杠 \\ 在路径
• macOS/Linux使用 正斜杠 / 在路径
• Claude配置使用 --directory 用于更好地处理项目路径的标志
• 确保根据您的操作系统匹配正确的格式，以避免错误

重要提示：

• 替换 FULL_PATH 带有项目目录的实际绝对路径
• 在保存配置更改之后， 重新启动MCP客户端 应用新设置
• 对于Cursor中的项目特定工具，请创建 .cursor/mcp.json 项目目录中的文件
• 对于Cursor中的全局工具，创建 ~/.cursor/mcp.json 主目录中的文件

对于可流式传输的http（建议用于远程MCP服务器）：

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

兼容的MCP客户端

点击任何客户访问其官方MCP设置文档：

添加配置后，MCP服务器应在MCP客户端中可见。

🔧 配置选项

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

环境变量

命令行参数

传输协议

配置优先

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

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

注： 运行服务器时不需要传递每个参数。但是，您必须提供元数据库URL和API密钥。任何未指定的参数都将使用如上所示的默认值。

🔑 获取您的Metabase API密钥

获取Metabase API密钥：

1. 登录Metabase实例
2. 点击您的个人资料图片 （右上角）
3. 选择“帐户设置”
4. 导航到“API密钥”选项卡
5. 单击“创建API密钥”
6. 给你的钥匙起一个描述性的名字 （例如，“MCP服务器密钥”）
7. 复制生成的密钥 （开始于 mb_)

⚠️ 重要提示： 安全地存储API密钥，永远不要将其提交到版本控制。该密钥提供对Metabase实例的完全访问权限。

📂 DXT文件支持

您不再需要经历克隆存储库和设置环境的步骤。只需按照以下步骤安装 元数据库MCP服务器 在你的 Cloude桌面应用程序:

1. 下载DXT文件
   请查看以下链接以下载最新版本 DXT文件 直接：
   下载DXT文件

2. 打开Cloude桌面应用程序
   一旦你有了文件，打开 Cloude桌面应用程序 在您的系统上。

3. 导航到扩展设置
   在 Cloude桌面应用程序:

   • 首选 文件 → 设置 → 扩展
   • 然后单击 高级设置.

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

5. 输入所需的详细信息
   挑选之后 DXT文件，将出现一个提示，要求您填写所需的详细信息：

   • 元数据库URL：输入元数据库服务器URL。
   • API密钥：添加相关的API密钥进行身份验证。

6. 完成设置
   输入必要的详细信息后，单击 保存 以应用该配置。

就是这样！这 元数据库MCP服务器 现在已安装并准备在您的 Cloude桌面应用程序.

如何创建自己的DXT文件

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

🚀 远程部署

对于生产使用或团队协作，您可以远程部署元数据库MCP服务器。我们在Codenunut内部使用这种方法。

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=DEBUG
    restart: unless-stopped

连接到远程MCP服务器

部署后，配置MCP客户端以连接到远程服务器：

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

部署选项

• 云提供商： AWS ECS、Google Cloud Run、Azure容器实例
• VPS/专用服务器： DigitalOcean、Linode、Vultr
• 集装箱平台： Kubernetes、Docker Swarm
• 平台即服务： 铁路，渲染，Fly.io

安全考虑

• 在生产环境中使用HTTPS
• 实施适当的防火墙规则
• 考虑使用VPN访问敏感业务数据
• 定期旋转API键
• 监控访问日志

需要部署方面的帮助吗？

CodeWalnut的团队提供部署和咨询服务。 联系我们 用于企业级设置和支持。

🔍 使用MCP检查器进行调试

要调试和测试元数据库MCP服务器设置，您可以使用官方的MCP检查器工具。

先决条件

首先，如果你还没有安装Node.js：

• 下载地址： nodejs.org
• 或者通过软件包管理器安装：
  复制

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

安装并运行MCP检查器

# 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检查器

MCP检查员提供：

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

运行后，打开浏览器 http://localhost:5173 访问检查器界面。

常见调试场景

• 连接问题 -验证您的元数据库URL和API密钥
• 权限错误 -检查您的API密钥是否具有所需的权限

🔧 可用工具

🧪 示例提示尝试

• 创建一个名为“航班概览”的仪表板，其中包含一个按目的地城市显示航班的条形图。
• 运行SQL： SELECT origin, destination, COUNT(*) FROM flights GROUP BY origin, destination LIMIT 10.
• 创建一张卡片，按地区分组显示上个月的总预订量。
• 删除名为“放弃的查询”的图表。
• 更新仪表板“销售KPI”，以包含新的收入卡。
• 显示“管理员”组中的所有用户。
• 创建一个名为“财务分析师”的新小组。
• 连接到Supabase数据库并列出所有表。

🌐 联系我们

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

🏢 官方链接

• 🌍 网站： codewalnut.com
• 📧 电子邮件： nattu@codewalnut.com
• 📖 博客：
  • 洞察力： codewalnut.com/insights
  • 学习： codewalnut.com/learn

📱 社交媒体

• 💼 领英： 代码胡桃木
• 📺 油管 CodeWalnut频道
• 🐦 推特/X： @胡桃木
• 📷 Instagram： @胡桃木

💬 社区支持

• 📧 通讯： 订阅CodeWalnut时事通讯 （向下滚动以找到电子邮件订阅选项）
• 🐙 github： 阿米拉莫/mcp代谢库

🤝 专业服务

• 咨询： 自定义元数据库集成和AI解决方案
• 培训： MCP和商业智能研讨会
• 技术支持： 企业级支持和维护

📢 关注我们，了解新MCP服务器、人工智能集成和商业智能工具的更新！

📜 许可证

该项目根据 Apache许可证2.0.

您可以在 LICENSE 文件。