# @easecloudio/mcp-metabase-server 中文文档

规范地址：https://npmcn.com/package/%40easecloudio/mcp-metabase-server/

版本：1\.3\.0
npm 元数据更新时间：2026-05-14T12:56:36.576Z
中文译文更新时间：2026-11-13T03:41:51.900Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40easecloudio/mcp-metabase-server
原文对照：https://npmcn.com/package/%40easecloudio/mcp-metabase-server/?lang=original
项目主页：https://github.com/easecloudio/mcp-metabase-server
源码仓库：https://github.com/easecloudio/mcp-metabase-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：195 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2025-07-19T19:40:30.295Z
- 最新版本发布：2026-05-14T12:56:36.461Z
- 近 30 天下载量：4162（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 6 个）

## 中文简介

Metabase的MCP服务器——96个工具,涵盖仪表板,卡片,数据库,表格,收藏,公共共享,chema缓存,以及SQL-to-MBQL转换

## 安装

```sh
npm install @easecloudio/mcp-metabase-server
```

也可以使用：`pnpm add @easecloudio/mcp-metabase-server`、`yarn add @easecloudio/mcp-metabase-server`、`bun add @easecloudio/mcp-metabase-server`

## README

# Metabase MCP 服务器

[![npm version](https://img.shields.io/npm/v/@easecloudio/mcp-metabase-server)](https://www.npmjs.com/package/@easecloudio/mcp-metabase-server) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![GitHub](https://img.shields.io/badge/GitHub-easecloudio%2Fmcp--metabase--server-blue)](https://github.com/easecloudio/mcp-metabase-server)

A 类 **Metabase 的模型上下文协议服务器** 它让AI助手可以完全进入你的分析平台——仪表板,卡片,数据库,表格,收藏品等等.

**开发和维护 [简单云](https://easecloud.io/)** ——云原性,AI驱动,和数据基础设施解决方案.

## 快速启动

```bash
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @easecloudio/mcp-metabase-server
```

## 96 可用工具

| 域名 | 工具 |
| --- | --- |
| 板板管理 | 27个 |
| 卡 / 问题管理 | 21国 |
| 数据库管理 | 16个 |
| 表格管理 | 页:1 |
| 收藏、用户和搜索 | 第13条 |
| Schema 缓存( SQL- MBQL) | 2个 |

## 支持的元库版本

-   Metabase v.046.x及以上(建议:v.048.x或后期)
-   Metabase Cloud( 完全支持)
-   自办案件(Docker、JAR或云层部署)

## 安装

### npx( 建议)

```bash
npx @easecloudio/mcp-metabase-server
```

### 全局安装

```bash
npm install -g @easecloudio/mcp-metabase-server
mcp-metabase-server
```

### 夹克

```bash
docker build -t mcp-metabase-server .
docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  mcp-metabase-server
```

## 配置

### 认证

**API 密钥( 首选 ) :**

```bash
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_metabase_api_key
```

**用户名/ 密码( 回落) :**

```bash
METABASE_URL=https://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
```

复制 `.env.example` 改为 `.env` 并填写您的值.

### 工具过滤( TOOL MODE)

设定 `TOOL_MODE` 控制哪些工具暴露于AI. 用于限制地表面积或防止意外写作.

| 模式 | 说明 |
| --- | --- |
| `all` | 每个可用的工具( 默认) |
| `essential` | 核心读取 + 执行工具 |
| `read` | 所有无损工具 |
| `write` | 所有工具,包括创建/更新/删除 |

```bash
TOOL_MODE=essential  # smallest surface area
TOOL_MODE=read       # read-only
TOOL_MODE=all        # everything (default)
```

## 克劳德桌面集成

马可斯: `~/Library/Application Support/Claude/claude_desktop_config.json` 窗口 : `%APPDATA%/Claude/claude_desktop_config.json`

**使用 npx :**

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}
```

**通过工具过滤 :**

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key",
        "TOOL_MODE": "essential"
      }
    }
  }
}
```

**使用本地建筑:**

```json
{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}
```

**用户名/ 密码倒置 :**

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password"
      }
    }
  }
}
```

## 可用工具

**Dashboard 管理(27个工具)**

### 核心 CRUD

| 工具 | 说明 |
| --- | --- |
| `list_dashboards` | 列出所有仪表板 |
| `get_dashboard` | 通过身份识别获得特定的仪表板 |
| `create_dashboard` | 创建新仪表板 |
| `update_dashboard` | 更新现有的仪表板 |
| `delete_dashboard` | 删除/ 归档一个仪表板 |
| `copy_dashboard` | 复制一个仪表板(shallow或深层复制件) |
| `save_dashboard` | 保存带嵌入数据的全部仪表板对象 |
| `save_dashboard_to_collection` | 将仪表板移动到特定的收藏中 |
| `search_dashboards` | 按名称或说明分列的搜索仪表板 |
| `favorite_dashboard` | 将仪表板标为最喜欢的 |
| `unfavorite_dashboard` | 从最爱中删除一个仪表板 |

### 卡片布局

| 工具 | 说明 |
| --- | --- |
| `get_dashboard_cards` | 把所有牌都装入仪表盘 |
| `add_card_to_dashboard` | 添加带有定位的牌 |
| `add_text_block` | 在仪表板上添加文本或标题块 |
| `remove_card_from_dashboard` | 删除一张牌 |
| `update_dashboard_card` | 更新卡片位置、大小和设置 |
| `update_dashboard_cards` | 把所有牌都换到仪表板上 |
| `update_dashcard` | 更新特定的破折卡属性 |
| `execute_dashboard_card` | 执行特定的破折卡并返回结果 |

### 公共共享和嵌入

| 工具 | 说明 |
| --- | --- |
| `create_dashboard_public_link` | 创建公共共享链接 |
| `delete_dashboard_public_link` | 删除公共链接 |
| `list_public_dashboards` | 列出带有公共链接的仪表板 |
| `list_embeddable_dashboards` | 启用用于嵌入的列表仪表板 |

### 修订、审计和发现

| 工具 | 说明 |
| --- | --- |
| `get_dashboard_revisions` | 获取修订历史( 审计线索) |
| `revert_dashboard` | 还原到以前的修订版 |
| `get_dashboard_related` | 获取相关内容建议 |
| `get_dashboard_queries` | 用已解析的字段ID提取所有卡查询 |

**卡片/问题管理(21个工具)**

### 核心 CRUD

| 工具 | 说明 |
| --- | --- |
| `list_cards` | 列出所有问题/ 牌 |
| `get_card` | 通过ID获取卡片(包括完整的SQL/MBQL查询) |
| `create_card` | 创建新问题 |
| `update_card` | 更新现有问题 |
| `delete_card` | 删除/ 归档一个问题 |
| `copy_card` | 复制一张牌 |
| `move_cards` | 将一张或多张牌移动到不同的收藏 |
| `move_cards_to_collection` | 从来源收藏中移动散列卡 |

### 执行导出( E)

| 工具 | 说明 |
| --- | --- |
| `execute_card` | 运行卡片并返回结果 |
| `execute_pivot_card_query` | 运行格式为中枢表的卡片 |
| `export_card_result` | 导出结果为 CSV 或 JSON |

### 参数

| 工具 | 说明 |
| --- | --- |
| `get_card_param_values` | 获取卡片参数的可用值 |
| `search_card_param_values` | 搜索/ 过滤参数值 |
| `get_card_param_remapping` | 获取要重映射的参数值 |

### 元数据发现( D)

| 工具 | 说明 |
| --- | --- |
| `get_card_query_metadata` | 获取列类型并显示名称 |
| `get_card_dashboards` | 列出包含此卡的仪表板 |
| `get_card_series` | 获取序列数据或相关卡建议 |

### 公共共享和嵌入

| 工具 | 说明 |
| --- | --- |
| `create_card_public_link` | 创建公共共享链接 |
| `delete_card_public_link` | 删除公共链接 |
| `list_public_cards` | 有公共链接的列表卡 |
| `list_embeddable_cards` | 启用用于嵌入的列表卡 |

**数据库管理(16个工具)**

### 核心 CRUD

| 工具 | 说明 |
| --- | --- |
| `list_databases` | 列出所有数据库连接 |
| `get_database` | 通过ID获取特定数据库 |
| `create_database_connection` | 创建新数据库连接 |
| `update_database` | 更新数据库连接的配置或证书 |
| `delete_database` | 永久删除数据库连接 |
| `add_sample_database` | 以演示数据添加内置的 H2 样本数据库 |

### 查询

| 工具 | 说明 |
| --- | --- |
| `execute_query` | 根据数据库执行 SQL 查询 |

### Schema 同步( S)

| 工具 | 说明 |
| --- | --- |
| `get_database_schema` | 获取计划信息 |
| `get_database_tables` | 在数据库中获取所有表格 |
| `get_database_metadata` | 获取完整的元数据, 包括所有表格和字段ID |
| `list_database_schemas` | 在数据库中列出所有计划 |
| `sync_database_schema` | 触发计划元数据同步 |
| `get_database_sync_status` | 检查同步状态 |

### 诊断

| 工具 | 说明 |
| --- | --- |
| `check_database_health` | 检查连接健康 |
| `validate_database` | 保存前验证连接设置 |
| `test_database_connection` | 测试已有的连接 |

**表管理(17个工具)**

### 元数据

| 工具 | 说明 |
| --- | --- |
| `list_tables` | 列表表格(可选择通过数据库过滤) |
| `get_table` | 按 ID 获取表格元数据 |
| `get_table_metadata` | 获取完整查询元数据,包括字段ID和类型 |
| `get_table_fks` | 获得外国关键关系 |
| `get_table_related` | 通过 FK 关系查找相关表格 |
| `get_table_data` | 从表格中获取样本数据预览 |
| `get_field_id` | 按表 ID + 列名查找字段标识( 返回 MBQL ref) |

### 卡片虚拟表格

| 工具 | 说明 |
| --- | --- |
| `get_card_table_fks` | 获取卡片虚拟表格的 FK 关系 |
| `get_card_table_query_metadata` | 获取卡片虚拟表格的查询元数据 |

### 管理层

| 工具 | 说明 |
| --- | --- |
| `update_table` | 更新显示名称、描述或能见度 |
| `update_tables` | 使用相同配置的分批更新多个表格 |
| `reorder_table_fields` | 更改字段的显示顺序 |
| `sync_table_schema` | 触发特定表格的同步计划 |
| `rescan_table_field_values` | 重新扫描字段值( 更新过滤器下拉) |
| `discard_table_field_values` | 丢弃已缓存的字段值 |

### CSV上传( Metabase 管理表格)

| 工具 | 说明 |
| --- | --- |
| `append_csv_to_table` | 从 CSV 内容添加新行 |
| `replace_table_csv` | 用新的 CSV 内容替换所有表格数据 |

**收藏、用户和搜索( 13个工具)**

### 收款

| 工具 | 说明 |
| --- | --- |
| `list_collections` | 列出全部收藏 |
| `create_collection` | 创建新收藏 |
| `get_collection` | 获取收藏细节 |
| `update_collection` | 更新名称、描述、颜色或父目录 |
| `delete_collection` | 删除收藏及其内容 |
| `get_collection_items` | 列表卡、仪表板和分集 |
| `move_to_collection` | 将牌或仪表板移动到不同的收藏 |

### 用户

| 工具 | 说明 |
| --- | --- |
| `list_users` | 列出所有用户 |
| `create_user` | 创建新用户 |

### 权限

| 工具 | 说明 |
| --- | --- |
| `list_permission_groups` | 列出所有权限组 |
| `create_permission_group` | 创建新权限组 |

### 搜索

| 工具 | 说明 |
| --- | --- |
| `search_content` | 搜索所有Metabase内容 |

**Schema缓存 — SQL 到 MBQL (2个工具)**

这些工具使AI能够将原生的SQL问题转换为交互式的MBQL问题. Metabase对于这种转换没有REST API——它需要域ID,这些工具在当地缓存.

**如何运作:**

1.  `get_card` 提取SQL和 `database_id`
2.  `get_schema_cache` —— 获取表格 + MBQL 引用的字段ID 如 `["field", 42, null]`
3.  AI 使用缓存字段ID翻译 SQL → MBQL
4.  `create_card` - 保存新的交互式问题

缓存存储于 `~/.easecloud/metabase-mcp/cache/{url-hash}/` 24小时TTL和范围 每一个Metabase实例.

| 工具 | 说明 |
| --- | --- |
| `get_schema_cache` | 返回缓存计划( 如果缺少或 stale ) |
| `refresh_schema_cache` | 一个或所有数据库的强制更新缓存 |

## MCP 资源

直接通过 `metabase://` URIs : (英语)

| URI 资源 | 说明 |
| --- | --- |
| `metabase://dashboard/{id}` | 挂板细节 |
| `metabase://card/{id}` | 卡片/问题详情 |
| `metabase://database/{id}` | 数据库信息 |
| `metabase://collection/{id}` | 收集细节 |
| `metabase://user/{id}` | 用户信息 |
| `metabase://table/{id}` | 表格元数据 |
| `metabase://field/{id}` | 外地资料 |

## 发展

```bash
npm install
npm run build       # compile TypeScript → dist/
npm run watch       # incremental rebuild
npm run dev         # build + start
npm run inspector   # launch MCP Inspector for debugging
```

## 调试

MCP服务器通过stdio通信,这使得直接调试变得尴尬. 使用 [MCP 检查员](https://github.com/modelcontextprotocol/inspector)数字 :

```bash
npm run inspector
```

检查员提供浏览器UI,用于发送工具呼叫并检查回复.

## 关于 EaseCloud

EaseCloud是一家云咨询和解决方案公司,专门从事:

-   云内应用开发
-   AI和自动化集成
-   D. 发展业务和基础设施管理
-   数据分析和BI平台咨询

我们建立这个项目是为了促进开源的MCP生态系统,同时展示我们在集成、自动化和云解决方案方面的专长.

如果你的团队在规模上采用Metabase 或者想将AI与你的BI堆集成在一起, [联系](https://easecloud.io/) 我们为企业提供咨询、定制和管理下的支助.

📧 [支持@ accloud.io](mailto:support@easecloud.io) 🌐 [eleascloud.io (英语)](https://easecloud.io/)

## 错误报告与问题

找到错误还是有特性请求 ?

🐛 [创建 GitHub 问题](https://github.com/easecloudio/mcp-metabase-server/issues)

请包括:

-   元库版本
-   MCP 服务器版本
-   复制步骤
-   预期与实际行为
-   任何错误消息或日志

## 捐款

欢迎捐款。 访问 [GitHub 仓库](https://github.com/easecloudio/mcp-metabase-server) 提交问题或撤回请求.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40easecloudio/mcp-metabase-server/LICENSE) 详细情况.

## 常见问题

### @easecloudio/mcp-metabase-server 是什么？

Metabase的MCP服务器——96个工具,涵盖仪表板,卡片,数据库,表格,收藏,公共共享,chema缓存,以及SQL-to-MBQL转换

### 如何安装 @easecloudio/mcp-metabase-server？

在项目目录运行 npm install @easecloudio/mcp-metabase-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-metabase-server，可以用 npx mcp-metabase-server 直接运行。

### @easecloudio/mcp-metabase-server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/easecloudio\_\_mcp-metabase-server 是否存在。

### @easecloudio/mcp-metabase-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @easecloudio/mcp-metabase-server 可以商用吗？

@easecloudio/mcp-metabase-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @easecloudio/mcp-metabase-server 的下载量有多少？

根据 npm 官方下载统计，@easecloudio/mcp-metabase-server 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,162 次，日均约 139 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @easecloudio/mcp-metabase-server 还在维护吗？

最新版本 1\.3\.0 发布于 2026/05/14（6 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/07/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。