Metabase MCP Mab

元数据库MCP服务器

一个模型上下文协议（MCP）服务器，使LLM能够与Metabase实例交互。此服务器提供33个工具，用于查询卡片、仪表板、数据库、集合，并对Metabase安装执行查询。

🚀 快速开始

先决条件

• Node.js>=18.0.0 （要求 @modelcontextprotocol/sdk)
• npm （附带Node.js）

安装

1. 克隆或导航到项目目录：

   cd metabase-mcp-mab

1. 安装依赖项：

   npm install

1. 验证Node.js版本：

   node --version  # Should be >= 18.0.0

配置

服务器要求设置环境变量。当与Cursor/Claude Desktop一起使用时，请在您的 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "metabase-local": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-mab/src/server/index.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your-api-key-here"
      }
    }
  }
}

环境变量

• METABASE_URL （可选）：您的元数据库实例URL。默认为 https://data-metabase.swile.co
• METABASE_API_KEY （必需）：您的Metabase API密钥。 必须提供 -安全性没有默认值。

备注：API密钥是必需的，必须通过环境变量提供。出于安全原因，没有硬编码的默认值。

获取您的Metabase API密钥

1. 登录Metabase实例
2. 前往设置→ 帐户设置→ API密钥
3. 新建API密钥或使用现有密钥
4. 复制密钥并将其添加到您的 mcp.json 配置

📖 用法

使用Cursor/Claude桌面

配置后 mcp.json，您可以问LLMs以下问题：

"Get the SQL query for card ID 17033"
"List all cards in the database"
"Show me cards related to revenue"
"Execute card 17033 with parameters"
"What databases are available?"

直接服务器使用

直接运行服务器：

npm start

或者在开发模式下运行并自动重新加载：

npm run dev

程序化使用

import { createDefaultClient } from './src/client/cards.js';

const client = createDefaultClient();

// Get a specific card
const card = await client.getCard(17033);
console.log(card.sqlQuery);

// List all cards
const cards = await client.listCards('all');

// Search for cards
const revenueCards = await client.searchCards('revenue');

// Execute a query
const results = await client.executeCardQuery(17033, {param: 'value'});

🛠️ 可用工具

此MCP服务器提供 27工具 按类别组织：

卡片工具（问题/查询）

• get_card -获取卡片详细信息和SQL查询
• list_cards -列出带有过滤功能的卡片
• execute_card_query -执行已保存的查询
• execute_query_builder_card -使用参数执行查询构建器卡
• get_generated_sql -为查询构建器卡获取生成的SQL
• get_card_with_parameters -从仪表板URL提取卡信息

仪表板工具

• get_dashboard -获取仪表板详细信息
• list_dashboards -列出所有仪表板

数据库和表工具

• get_database -获取数据库信息
• list_databases -列出所有数据库
• get_database_metadata -获取全面的数据库架构
• list_database_tables -列出数据库中的表
• get_table_metadata -获取详细的表格信息

收藏工具

• list_collections -列出所有集合（文件夹）
• get_collection_items -获取收藏中的项目

查询执行

• execute_native_query -执行自定义SQL查询

字段和列工具

• get_field -获取字段/列信息
• get_field_values -获取字段的不同值

细分市场和指标

• list_segments -列出已保存的筛选器段
• list_metrics -列出已保存的聚合

活动和用户

• get_activity -获取最近的活动订阅源
• get_current_user -获取当前经过身份验证的用户
• list_users -列出所有用户（需要管理员）

有关所有工具的详细文档，请参阅 工具_参考.md.

📚 文档

• 用法\_ GIDE.md -带示例的完整使用指南
• 工具_参考.md -所有27种工具的详细参考

🏗️ 项目结构

metabase-mcp-mab/
├── src/
│   ├── server/
│   │   └── index.js          # Main MCP server implementation
│   └── client/
│       └── cards.js           # JavaScript client library
├── testing/
│   └── test-new-tools.js     # Test scripts
├── package.json              # Dependencies and scripts
├── README.md                 # This file
├── USAGE_GUIDE.md            # Usage documentation
└── TOOLS_REFERENCE.md        # Tools reference

🔧 发展

脚本

• npm start -运行服务器
• npm run dev -使用自动重新加载（监视模式）运行服务器

依赖项

• @modelcontextprotocol/sdk -MCP SDK框架
• axios -HTTP客户端库（尽管是原生的 fetch 使用）
• dotenv -环境变量管理

测试

运行测试脚本：

node testing/test-new-tools.js

⚠️ 重要说明

风险等级

• 🟢 安全工具：只读操作，不修改数据
• 🟡 中等风险工具：执行查询（只读，但可能速度慢/资源密集）

性能注意事项

• list_cards 可以返回15k+个项目-结果仅限于显示的前50个
• get_database_metadata 返回所有表和列-可能非常大
• execute_card_query 和 execute_native_query 复杂的查询可能需要时间
• 尽可能使用搜索操作，而不是列出所有内容

版本兼容性

某些工具可能并非在所有Metabase版本中都可用（例如。， list_metrics, get_activity).服务器优雅地处理缺失的端点。

🐛 故障排除

服务器无法启动

1. 检查Node.js版本：

   node --version  # Must be >= 18.0.0

1. 验证是否安装了依赖项：

   npm install

1. 检查环境变量：

- 确保 METABASE_API_KEY 已设置 mcp.json - 验证 METABASE_URL 正确（如果是自定义的）

API身份验证错误

• 验证API密钥是否正确且处于活动状态
• 检查API密钥是否具有必要的权限
• 确保元数据库URL可从您的网络访问

连接问题

• 验证元数据库实例是否正在运行且可访问
• 检查网络连接
• 确保防火墙规则允许连接

📝 许可证

国际学生委员会

🤝 贡献

欢迎投稿！请确保：

• Node.js>=18.0.0
• 所有测试均通过
• 代码遵循现有模式