AI导哈

Metabase MCP服务器

一个为AI代理提供对Metabase实例只读访问的MCP服务器，支持数据库查询、数据分析和导出功能。

  • by Arkanji
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Arkanji/metabase-mcp-server

使用说明

Metabase MCP Server

Connect any AI agent to your Metabase instance.
Read-only tools · MBQL + native SQL · cross-DB analysis · data export

Quick Start · Tools · Configuration · Examples · Troubleshooting

一 主控程序 为AI代理提供只读访问权限的服务器 元数据库 例子探索模式、查询数据库、运行保存的问题、跨数据库比较数据以及导出结果——所有这些都是通过自然对话完成的。

适用于Claude Code、Cursor和任何兼容MCP的客户端。

快速开始

git clone https://github.com/arkanji/metabase-mcp-server.git
cd metabase-mcp-server
npm install && npm run build

然后将其添加到您的AI客户端：

Claude Code — .mcp.json 
{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxx"
      }
    }
  }
}
Cursor — .cursor/mcp.json 
{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_xxxxxxxxxxxxx"
      }
    }
  }
}

配置

变量 必填 默认 描述
METABASE_URL 是 -- 您的元数据库实例URL。请执行 不 包含 /api.
METABASE_API_KEY 是 -- 如何生成一个 -转到“管理”>“设置”>“API密钥”。
METABASE_EXPORT_DIR 没有 ~/Downloads/ 在哪里 export_dataset 写入CSV/JSON文件。

工具

发现

工具 它做什么
list_databases 列出所有连接的数据库
list_tables 列出数据库中的表
get_table_fields 获取表的列名、ID和类型
preview_table 示例行以了解数据形状
search 按关键字查找已保存的问题、仪表板或表格

询问

工具 它做什么
query_dataset 运行结构化MBQL查询（聚合、过滤器、分组）
run_native_query 运行原始SQL查询（需要对API键拥有SQL权限）
run_saved_question 按ID执行已保存的问题
get_card_metadata 在不运行的情况下检查已保存问题的定义
list_saved_questions 列出所有已保存的问题，可选择按数据库列出

仪表盘

工具 它做什么
list_dashboards 列出所有仪表板
get_dashboard 获取仪表板的卡片和布局详细信息

分析与导出

工具 它做什么
cross_db_overlap 查找两个数据库中的重叠值（例如CRM和营销部门之间的共享电子邮件）
export_dataset 使用自动分页功能将最多50万行导出为CSV/JSON

示例

“上个月我们接到了多少订单？”

代理人将：

  1. list_databases → 查找您的订单数据库
  2. list_tables → 查找订单表
  3. get_table_fields → 获取日期和状态字段ID
  4. query_dataset → 使用日期筛选器运行计数聚合

“将所有活跃客户导出到CSV”

代理人将：

  1. 发现表和字段ID
  2. export_dataset → 自动分页通过2000行元数据库上限，写入 ~/Downloads/

“哪些客户同时存在于我们的CRM和营销数据库中？”

代理人将：

  1. 识别两个数据库中的电子邮件字段
  2. cross_db_overlap → 获取两侧，在内存中计算交点

运作原理

You ──→ AI Agent ──→ MCP Server ──→ Metabase REST API ──→ Your Databases
         (Claude,      (this       (x-api-key auth,
          Cursor)       project)    read-only)

需要了解的关键事项：

  • 只读 --没有写操作。验证本机SQL查询以拒绝 INSERT, UPDATE, DELETE, DROP等等。
  • 2000排帽 --元数据库将查询结果限制为2000行。使用聚合进行分析，或 export_dataset 用于完整数据提取（自动分页高达500K行）。
  • 30秒超时 -每个API请求在30秒后超时，以防止挂起连接。
  • MBQL --元数据库的结构化查询语言。列由字段ID（而不是名称）引用，因此始终调用 get_table_fields 先去查一下。

安全

  • API密钥 通过环境变量传递，并作为 x-api-key 标题。它们从未在工具响应中记录或公开。
  • 写入操作保护 — run_native_query 拒绝以write关键字开头的查询(INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE).这是一个基本的前缀检查，而不是一个全面的SQL解析器——元数据库自己的权限系统是主要的访问控制。
  • 代码中没有秘密 --服务器在启动时仅从env-var读取凭据。

故障排除

问题 原因 修复
METABASE_URL environment variable is required 缺少环境变量 集 METABASE_URL 在你的 .mcp.json env块或shell
Metabase API error 401 无效或过期的API密钥 在元数据库管理>设置>API密钥中生成新密钥
Metabase API error 403 密钥缺少此操作的权限 请在元数据库中检查密钥的权限组。本机SQL需要显式的“本机查询”权限。
Metabase API returned empty response URL错误或元数据库已关闭 验证 METABASE_URL 指向您的实例（无尾随 /api)
Write operations are not allowed SQL查询以INSERT/UPDATE等开头。 此服务器是只读的。仅使用SELECT查询。
查询返回空结果 字段ID或筛选器错误 调用 get_table_fields 要验证字段ID，则 preview_table 检查数据形状
导出挂起 非常大的数据集+缓慢的元数据库 添加过滤器以减少行数。出口上限为50万行。

发展

npm run dev      # Watch mode — recompiles on save
npm run build    # One-time build
npm start        # Run the server

应适用于支持以下功能的任何Metabase版本 /api/dataset 端点和API密钥认证（一般为v0.44+）。

贡献

欢迎发布问题和PR。请打开 问题 首先讨论重大变化。

许可证

麻省理工学院

Built by Arkanji

相关 MCP