Metabase MCP Server

Metabase MCP 服务 - 将 AI 助手连接到 Metabase 分析平台

一款面向 Metabase 的高性能 Model Context Protocol（MCP）服务，让 Claude、Cursor 等 AI 助手和其他 MCP 客户端能够无缝连接您的 Metabase 实例。借助 AI 驱动的数据库操作，您可以查询数据库、执行 SQL、管理仪表板，并通过自然语言自动化分析工作流。

适用对象： 希望将 AI 助手集成到 Metabase 商业智能平台的分析师、开发者和团队，从而自动执行 SQL 查询、管理仪表板和探索数据。

主要功能

数据库操作

• 列出数据库：浏览所有已配置的 Metabase 数据库
• 发现数据表：查看数据表及其元数据和描述
• 检查字段：获取详细的字段／列信息，并支持智能分页

查询与分析

• 执行 SQL：运行支持参数和模板的原生 SQL 查询
• MongoDB 支持：执行原生 MongoDB 查询，并自动将聚合管道转换为 JSON
• 卡片管理：执行、创建和管理 Metabase 问题／卡片（SQL 和 MongoDB）
• 集合整理：创建和管理集合，方便整理内容
• 自然语言查询：让 AI 助手将问题转换为 SQL 或 MongoDB 查询

身份验证与安全

• API 密钥支持：通过 Metabase API 密钥进行安全身份验证（推荐）
• 基于会话的身份验证：可选的电子邮件／密码身份验证方式
• 环境变量：通过 .env 文件安全管理凭据

AI 助手集成

• Claude Desktop：原生集成 Anthropic 的 Claude AI
• Cursor IDE：无缝集成，支持 AI 辅助开发
• 任意 MCP 客户端：兼容所有 Model Context Protocol 客户端

性能与可靠性增强

• 上下文感知日志记录：实时记录调试、信息、警告和错误级别的日志，并向 AI 客户端显示
• 完善的错误处理：使用 FastMCP 的 ToolError 异常，提供更清晰的错误消息并便于调试
• 中间件栈：内置错误处理和日志记录中间件，确保生产环境的可靠性
• 最佳实践：遵循最新的 FastMCP 模式，避免重复并保持配置简洁
• 现代 Python：使用 Python 3.12+ 类型提示（| 语法），提升类型安全性

快速开始

前提条件

• Python 3.12+
• 可通过 API 访问的 Metabase 实例
• uvx 或 uv 包管理器

安装

选项 1：使用 uvx（最简单，无需安装）

# Run directly without installing (like npx for Python)
uvx metabase-mcp

# With environment variables
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

选项 2：从 PyPI 安装

# Install globally
uv tool install metabase-mcp

# Or with pip
pip install metabase-mcp

# Then run
metabase-mcp

选项 3：开发环境设置（从源代码安装）

# Clone the repository
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp

# Install dependencies
uv sync

# Run the server
uv run python server.py

配置

创建 .env 文件，填入您的 Metabase 凭据：

cp .env.example .env

配置选项

选项 1：API 密钥身份验证（推荐）

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

选项 2：电子邮件／密码身份验证

METABASE_URL=https://your-metabase-instance.com
[email protected]
METABASE_PASSWORD=your-password

可选：Metabase API HTTP 超时时间

METABASE_HTTP_TIMEOUT=30.0  # Default: 30.0 seconds

可选：自定义 SSE／HTTP 主机／端口

HOST=localhost  # Default: 0.0.0.0
PORT=9000      # Default: 8000

使用方法

运行服务

快速开始（无需设置）

# Run directly with uvx
uvx metabase-mcp

# With custom Metabase instance
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

从源代码运行（开发环境）

# STDIO transport (default)
uv run python server.py

# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --sse

# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --http

# Custom host and port via environment variables
HOST=localhost PORT=9000 uv run python server.py --sse
HOST=192.168.1.100 PORT=8080 uv run python server.py --http

Cursor 集成

您可以通过编辑 Cursor 设置，手动配置 Cursor。

对于 SSE 传输：使用 Cursor 前，必须先启动服务：

uv run python server.py --sse

Claude Desktop 集成

选项 1：使用 uvx（推荐）

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uvx",
            "args": ["metabase-mcp"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

选项 2：使用本地安装

如果你已克隆此仓库：

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/absolute/path/to/metabase-mcp",
                "python",
                "server.py"
            ],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

选项 3：使用 FastMCP CLI

fastmcp install server.py -n "Metabase MCP"

可用工具

数据库操作

工具	描述
list_databases	列出 Metabase 中所有已配置的数据库
list_tables	获取指定数据库中的所有表及其元数据
get_table_fields	获取表的字段／列信息

查询操作

工具	描述
execute_query	执行支持参数的原生 SQL 查询
execute_mongodb_query	执行原生 MongoDB 查询，并自动将聚合管道转换为 JSON
execute_card	运行已保存的 Metabase 问题／卡片

卡片管理

工具	描述
list_cards	列出所有已保存的问题／卡片
create_card	使用 SQL 查询创建新问题／卡片
create_mongodb_card	使用原生查询支持创建新的 MongoDB 问题／卡片

集合管理

工具	描述
list_collections	浏览所有集合
create_collection	创建新集合以便组织管理

传输方式

此服务支持多种传输方式：

• STDIO（默认）：用于 IDE 集成（Cursor、Claude Desktop）
• SSE：用于 Web 应用的服务器发送事件
• HTTP：用于 API 访问的标准 HTTP

uv run python server.py                        # STDIO (default)
uv run python server.py --sse                  # SSE (HOST=0.0.0.0, PORT=8000)
uv run python server.py --http                 # HTTP (HOST=0.0.0.0, PORT=8000)
HOST=localhost PORT=9000 uv run python server.py --sse   # Custom host/port

开发

设置开发环境

# Install with dev dependencies
uv sync --group dev

# Or with pip
pip install -r requirements-dev.txt

代码质量

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy server.py

使用示例

查询示例

# List all databases
databases = await list_databases()

# Execute a SQL query
result = await execute_query(
    database_id=1,
    query="SELECT * FROM users LIMIT 10"
)

# Create and run a card
card = await create_card(
    name="Active Users Report",
    database_id=1,
    query="SELECT COUNT(*) FROM users WHERE active = true",
    collection_id=2
)

项目结构

metabase-mcp/
├── server.py                 # Main MCP server implementation
├── pyproject.toml           # Project configuration and dependencies
└── .env.example             # Environment variables template

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

MIT 许可证——详情请参阅 LICENSE 文件

资源

• FastMCP 文档
• Model Context Protocol
• Metabase API 文档
• Claude Desktop 文档
• Cursor IDE

关键词与主题

metabase mcp model-context-protocol claude cursor ai-assistant fastmcp sql database analytics business-intelligence bi data-analysis anthropic llm python automation api data-science query-builder natural-language-sql

Star 历史

如果你觉得这个项目有用，请考虑给它点个星！这有助于其他人发现此工具。

使用场景

• 自然语言数据库查询：使用日常语言让 Claude 查询你的 Metabase 数据库
• 自动生成报告：使用 AI 创建和管理 Metabase 卡片与集合
• 数据探索：让 AI 助手帮助你从数据中发现洞见
• SQL 查询辅助：通过 AI 获取编写和优化 SQL 查询的帮助
• 仪表板管理：自动创建和整理 Metabase 仪表板
• 数据分析工作流：将 AI 驱动的分析集成到你的开发工作流中