元数据库-MCP

Name: 元数据库-MCP
Author: cheukyin175

作者：cheukyin17523 星标更新：2025-10-10

安装使用来源：spider==github.com

项目介绍

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

一个高性能的模型上下文协议（MCP）服务器，用于Metabase，使像Claude、Cursor和其他MCP客户端能够无缝地与您的Metabase实例交互。通过AI驱动的数据库操作查询数据库、执行SQL、管理仪表板并自动化分析工作流程。

适用于： 数据分析师、开发者和团队，他们希望将AI助手集成到他们的Metabase商业智能平台中，以实现自动化的SQL查询、仪表板管理和数据探索。

主要特性

数据库操作

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

查询与分析

SQL执行：运行原生SQL查询，支持参数和模板
卡片管理：执行、创建和管理Metabase问题/卡片
集合组织：创建和管理集合以更好地组织
自然语言查询：让AI助手将问题翻译成SQL

认证与安全

API密钥支持：通过Metabase API密钥进行安全认证（推荐）
基于会话的认证：替代的电子邮件/密码认证
环境变量：通过.env文件进行安全凭证管理

AI助手集成

Claude桌面：与Anthropic的Claude AI原生集成
Cursor IDE：无缝集成用于AI辅助开发
任何MCP客户端：兼容所有模型上下文协议客户端

增强性能与可靠性

上下文感知日志：实时日志记录，AI客户端可见的调试、信息、警告和错误级别
适当的错误处理：FastMCP ToolError 异常，提供更好的错误消息和调试
中间件堆栈：内置的错误处理和日志中间件，确保生产可靠性
最佳实践：遵循最新的FastMMCP模式，防止重复并保持干净的配置
现代Python：使用Python 3.12+ 类型提示（| 语法），提高类型安全性

快速开始

先决条件

Python 3.12+
具有API访问权限的Metabase实例
uvx 或 uv 包管理器

安装

选项1：使用uvx（最简单 - 不需要安装）

# 直接运行而不安装（类似于npx对Python）
uvx metabase-mcp

# 使用环境变量
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

选项2：从PyPI安装

# 全局安装
uv tool install metabase-mcp

# 或者使用pip
pip install metabase-mcp

# 然后运行
metabase-mcp

选项3：开发设置（从源码）

# 克隆仓库
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp

# 安装依赖
uv sync

# 运行服务器
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
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-password

可选：自定义主机/端口用于SSE/HTTP

HOST=localhost  # 默认：0.0.0.0
PORT=9000      # 默认：8000

使用方法

运行服务器

快速开始（无需设置）

# 直接使用uvx运行
uvx metabase-mcp

# 使用自定义Metabase实例
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

从源码（开发）

# STDIO传输（默认）
uv run python server.py

# SSE传输（默认使用HOST=0.0.0.0, PORT=8000）
uv run python server.py --sse

# HTTP传输（默认使用HOST=0.0.0.0, PORT=10000）
uv run python server.py --http

# 通过环境变量使用自定义主机和端口
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桌面集成

选项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_card`	运行保存的Metabase问题/卡片

卡片管理

工具	描述
`list_cards`	列出所有保存的问题/卡片
`create_card`	创建新的问题/卡片，使用SQL查询

集合管理

工具	描述
`list_collections`	浏览所有集合
`create_collection`	创建新的集合以进行组织

传输方法

服务器支持多种传输方法：

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

uv run python server.py                        # STDIO（默认）
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   # 自定义主机/端口

开发

设置开发环境

# 安装开发依赖
uv sync --group dev

# 或者使用pip
pip install -r requirements-dev.txt

代码质量

# 运行代码检查
uv run ruff check .

# 格式化代码
uv run ruff format .

# 类型检查
uv run mypy server.py

使用示例

查询示例

# 列出所有数据库
databases = await list_databases()

# 执行SQL查询
result = await execute_query(
    database_id=1,
    query="SELECT * FROM users LIMIT 10"
)

# 创建并运行卡片
card = await create_card(
    name="活跃用户报告",
    database_id=1,
    query="SELECT COUNT(*) FROM users WHERE active = true",
    collection_id=2
)

项目结构

metabase-mcp/
├── server.py                 # 主MCP服务器实现
├── pyproject.toml           # 项目配置和依赖项
└── .env.example             # 环境变量模板

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT许可证 - 详情见LICENSE文件

资源

关键词与主题

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

星标历史

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

使用案例

自然语言数据库查询：让Claude使用纯英语查询您的Metabase数据库
自动化报告生成：使用AI创建和管理Metabase卡片和集合
数据探索：让AI助手帮助您发现数据中的见解
SQL查询协助：通过AI获得编写和优化SQL查询的帮助
仪表板管理：自动化Metabase仪表板的创建和组织
数据分析工作流：将AI驱动的分析集成到您的开发工作流中