Metabase MCP 服务器

一个模型控制协议 (MCP) 服务器，使 AI 助手能够与 Metabase 数据库和操作进行交互。

![Metabase MCP 服务器]

概述

Metabase MCP 服务器提供了一个 AI 助手和 Metabase 之间的桥梁，允许 AI 模型：

• 列出和浏览 Metabase 中配置的数据库
• 检索关于数据库模式、表和字段的详细元数据
• 可视化数据库中表之间的关系
• 列出和执行 Metabase 操作
• 通过安全的 API 对 Metabase 数据执行操作

该服务器实现了 [模型控制协议 (MCP)] 规范，使其与支持 MCP 工具的 AI 助手兼容。

特性

• 数据库浏览: 列出所有数据库并浏览它们的模式
• 元数据检索: 获取关于表、字段和关系的详细信息
• 关系可视化: 生成数据库关系的可视化表示
• 操作管理: 列出、查看详细信息和执行 Metabase 操作
• 安全 API 密钥处理: 加密存储 API 密钥并防止泄露
• Web 界面: 通过用户友好的 Web 界面测试和调试功能
• Docker 支持: 使用 Docker 和 Docker Compose 轻松部署

前提条件

• Metabase 实例（建议 v0.46.0 或更高版本）
• 具有适当权限的 Metabase API 密钥
• Docker（用于容器化部署）
• Python 3.10+（用于本地开发）

安装

使用 Docker (推荐)

1. 克隆此存储库：

   git clone https://github.com/yourusername/metabase-mcp.git
   cd metabase-mcp
   

2. 构建并运行 Docker 容器：

   docker-compose up -d
   

3. 访问配置界面：http://localhost:5001

手动安装

1. 克隆此存储库：

   git clone https://github.com/yourusername/metabase-mcp.git
   cd metabase-mcp
   

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 运行配置界面：

   python -m src.server.web_interface
   

4. 访问配置界面：http://localhost:5000

配置

1. 在浏览器中打开 Web 界面
2. 输入您的 Metabase URL（例如，http://localhost:3000）
3. 输入您的 Metabase API 密钥
4. 点击“保存配置”并测试连接

获取 Metabase API 密钥

1. 以管理员身份登录到您的 Metabase 实例
2. 转到设置 > 管理设置 > API 密钥
3. 创建具有适当权限的新 API 密钥
4. 复制生成的密钥以在 MCP 服务器中使用

用法

运行 MCP 服务器

配置完成后，您可以运行 MCP 服务器：

# 使用 Docker
docker run -p 5001:5000 metabase-mcp

# 手动
python -m src.server.mcp_server

可用工具

MCP 服务器为 AI 助手提供以下工具：

1. list_databases: 列出 Metabase 中配置的所有数据库
2. get_database_metadata: 获取特定数据库的详细元数据
3. db_overview: 获取数据库中所有表的高级概述
4. table_detail: 获取关于特定表的详细信息
5. visualize_database_relationships: 生成数据库关系的可视化表示
6. run_database_query: 对数据库执行 SQL 查询
7. list_actions: 列出 Metabase 中配置的所有操作
8. get_action_details: 获取关于特定操作的详细信息
9. execute_action: 使用参数执行 Metabase 操作

通过 Web 界面测试工具

Web 界面为每个工具提供了一个测试区域：

1. List Databases: 查看 Metabase 中配置的所有数据库
2. Get Database Metadata: 查看数据库的详细模式信息
3. DB Overview: 查看数据库中所有表的简洁列表
4. Table Detail: 查看关于特定表的详细信息
5. Visualize Database Relationships: 生成表关系的可视化表示
6. Run Query: 对数据库执行 SQL 查询
7. List Actions: 查看 Metabase 中配置的所有操作
8. Get Action Details: 查看关于特定操作的详细信息
9. Execute Action: 测试使用参数执行操作

安全注意事项

• API 密钥以加密形式静态存储
• Web 界面永远不会以纯文本形式显示 API 密钥
• 当配置了安全的 Metabase URL 时，所有 API 请求都使用 HTTPS
• 该服务器应部署在生产环境中的安全代理后面

开发

项目结构

metabase-mcp/
├── src/
│   ├── api/            # Metabase API 客户端
│   ├── config/         # 配置管理
│   ├── server/         # MCP 和 Web 服务器
│   └── tools/          # 工具实现
├── templates/          # Web 界面模板
├── docker-compose.yml  # Docker Compose 配置
├── Dockerfile          # Docker 构建配置
├── requirements.txt    # Python 依赖项
└── README.md           # 文档

添加新工具

要添加新工具：

1. 在 src/tools/ 中实现工具函数
2. 在 src/server/mcp_server.py 中注册该工具
3. 在 templates/config.html 中添加测试界面（可选）
4. 在 src/server/web_interface.py 中添加路由（如果添加测试界面）

故障排除

常见问题

• 连接失败: 确保您的 Metabase URL 正确且可访问
• 身份验证错误: 验证您的 API 密钥是否具有必要的权限
• Docker 网络问题: 使用 Docker 时，确保正确的网络配置

日志

检查日志以获取详细的错误信息：

# Docker 日志
docker logs metabase-mcp

# 手动执行日志
# 日志打印到控制台

贡献

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