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

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

版本：2\.2\.0
npm 元数据更新时间：2026-09-17T01:01:14.450Z
中文译文更新时间：2026-11-10T10:04:20.155Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：199 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.19\.0
- 运行依赖：7 个
- 首次发布：2025-08-27T14:06:18.947Z
- 最新版本发布：2026-08-17T21:02:54.811Z
- 近 30 天下载量：13593（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

Metabase 集成的示范背景协议服务器

## 安装

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

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

## README

# 读取: Metabase MCP 服务器

[![npm version](https://img.shields.io/npm/v/@cognitionai/metabase-mcp-server)](https://www.npmjs.com/package/@cognitionai/metabase-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-43853D?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)

一个用于Metabase集成的综合模型上下文协议(MCP)服务器,为AI助手提供了对Metabase分析平台的充分访问.

## QQ 快速启动

```bash
# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server
```

## \* 特性

### 🎯 **81+ 可用工具** - 完成元数据库API覆盖

-   **盘子管理** (23个工具) - 完整的CRUD操作,卡管理,公共共享,嵌入
-   **QQ卡/问题管理** (21个工具) - 查询执行,参数处理,枢轴查询,公共链接
-   **数据库管理** (13个工具) - 连接管理, schema同步, 查询执行
-   **表格管理** (16个工具) - 元数据操作,外地管理,数据操作
-   **+++ 附加工具** (9个工具) - 收藏,搜索,用户,活动跟踪,操场链接

## \* 安装

> **建议:** 20.19.0+和npm 8.0.0+ 最佳相容性节点

### 方法1: NPX(建议)

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

### 方法2:全球安装

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

### 方法 3: 嵌入器

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

## QQ 配置

### 环境变量

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

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

**用户名/ Password 认证( Fallback) :**

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

### 可选参数

服务器支持命令行参数自定义工具加载 :

-   **`--essential`** (默认):仅装入必要的工具
-   **`--all`**: 装入所有80+可用工具
-   **`--write`**: 只装入写入/修改工具
-   **`--read`**: 只装入只读工具

```bash
# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only
```

## 综合实例

### 克劳德桌面

添加到您的 Claude 桌面配置( E)`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上:

**使用已发布软件包 :**

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

**利用地方发展建设:**

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

**有自定义旗:**

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

### Windsurf IDE 风平浪静

添加到您的 Windsurf MCP 配置中(`~/.windsurf/mcp_config.json`:

**使用已发布软件包 :**

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

**利用地方发展建设:**

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

**有自定义旗:**

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

## 可用的工具

**\* 板板管理(23个工具)**

### 核心业务

-   `list_dashboards` - 列出所有仪表板
-   `get_dashboard` - 通过身份验证仪表板
-   `create_dashboard` - 创建新的仪表板
-   `update_dashboard` - 更新现有的仪表板
-   `delete_dashboard` - 删除仪表板
-   `copy_dashboard` - 复制仪表板

### 卡片管理

-   `get_dashboard_cards` - 把所有牌都装入仪表板
-   `add_card_to_dashboard` - 在仪表板上添加卡片
-   `remove_card_from_dashboard` - 从仪表板上取出卡片
-   `update_dashboard_card` - 更新卡片位置/设置
-   `execute_dashboard_card` - 执行具体的仪表板卡

### 公共共享和嵌入

-   `create_public_link` - 创建公共仪表板链接
-   `delete_public_link` - 删除公共仪表板链接
-   `list_public_dashboards` - 列出公共仪表板
-   `list_embeddable_dashboards` - 可嵌入式仪表板清单

### 参数和查询

-   `get_dashboard_param_values` - 获取参数值
-   `search_dashboard_param_values` - 搜索参数值
-   `get_dashboard_param_remapping` - 获得参数再映射
-   `execute_dashboard_query` - 执行仪表板查询

### 高级特性

-   `get_dashboard_related` - 获取相关内容
-   `get_dashboard_query_metadata` - 获取查询元数据
-   `update_dashboard_cards` - 散装更新卡
-   `save_dashboard` - 保存仪表板更改
-   `get_dashboard_items` - 获得仪表板项目

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

### 核心业务

-   `list_cards` - 列出所有牌/问题
-   `get_card` - 凭身份证拿卡
-   `create_card` - 创建新牌
-   `update_card` - 更新现有卡片
-   `delete_card` - 删除名片
-   `copy_card` - 复制卡

### 查询执行

-   `execute_card` - 执行卡查询
-   `execute_card_query_with_format` - 以具体格式执行
-   `execute_pivot_card_query` - 执行枢轴查询
-   `get_card_query_metadata` - 获取查询元数据

### 卡片管理

-   `move_cards` - 在收藏品之间移动牌
-   `move_cards_to_collection` - 散装移动到收藏
-   `get_card_dashboards` - 获得包含卡片的仪表板
-   `get_card_series` - 获取卡片系列数据

### 参数和值

-   `get_card_param_values` - 获取参数值
-   `search_card_param_values` - 搜索参数值
-   `get_card_param_remapping` - 获得参数再映射

### 公共分享

-   `create_card_public_link` - 创建公共卡链接
-   `delete_card_public_link` - 删除公用卡链接
-   `get_public_cards` - 列出公用卡
-   `get_embeddable_cards` - 可嵌入式卡片

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

### 核心业务

-   `list_databases` - 列出所有数据库
-   `get_database` - 获取数据库细节
-   `create_database` - 创建数据库连接
-   `update_database` - 更新数据库设置
-   `delete_database` - 删除数据库连接

### 元数据( M)

-   `get_database_schema_tables` - 获取数据库表格
-   `get_database_schemas` - 获取数据库计划
-   `get_database_metadata` - 获得完整的元数据
-   `sync_database_schema` - 同步元数据

### 查询操作

-   `execute_query` - 执行SQL查询
-   `execute_query_export` - 执行和出口结果

### 维修

-   `get_database_usage_info` - 获得使用统计
-   `rescan_database_field_values` - 重新扫描字段值

**\* 表格管理(16个工具)**

### 核心业务

-   `list_tables` - 带有过滤功能的列表表格
-   `get_table` - 获取桌子的细节
-   `update_table` - 更新表格配置
-   `update_tables` - 大量更新表格

### 数据操作

-   `get_table_data` - 检索表格数据
-   `append_csv_to_table` - 附加CSV数据
-   `replace_table_csv` - 替换为 CSV 数据

### Schema 关系( L)

-   `get_table_query_metadata` - 获取查询元数据
-   `get_table_fks` - 获得外国关键关系
-   `get_table_related` - 获取相关表格
-   `sync_table_schema` - 同步表格计划

### 外地管理

-   `reorder_table_fields` - 重新排序字段显示
-   `rescan_table_field_values` - 重新扫描字段值
-   `discard_table_field_values` - 丢弃缓存值

### 卡片整合

-   `get_card_table_fks` - 获得外国密钥的卡片表
-   `get_card_table_query_metadata` - 获取纸牌表格元数据

**\* 补充工具(9个工具)**

### 收款

-   `list_collections` - 列出所有收藏
-   `create_collection` - 创建新收藏
-   `update_collection` - 更新收藏
-   `delete_collection` - 删除收藏
-   `get_collection_items` - 获取收藏品

### 搜索发现( D)

-   `search_content` - 搜索所有内容

### 活动和分析

-   `get_recent_views` - 最近的活动
-   `get_popular_items` - 获得流行内容

### 游戏场地链接

-   `get_metabase_playground_link` - 创建互动游乐场链接

## 发展

### 设置

```bash
git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install
```

### 构建

```bash
npm run build
```

### 发展模式

```bash
npm run watch
```

### 调试

使用 MCP 检查器调试 :

```bash
npm run inspector
```

## 测试认证

### API 密钥认证

1.  设定 `METABASE_URL` 财务报告和审定财务报表 `METABASE_API_KEY`
2.  启动服务器并在日志中验证“ Using Metabase API 密钥”
3.  测试 `list_dashboards` 工具

### 用户名/ 名词认证

1.  未设置 `METABASE_API_KEY`
2.  设定 `METABASE_URL`, (中文(简体) ), `METABASE_USERNAME`, (中文(简体) ), `METABASE_PASSWORD`
3.  启动服务器并验证日志中的“ 使用用户名/ 密码字 ”
4.  测试 `list_dashboards` 工具

## \* 解决问题

### 共同问题

**认证错误 :**

-   校验您的 Metabase URL 可以访问
-   在 Metabase 管理员设置中检查 API 密钥有效性
-   确保用户名/密码证书正确无误

**连接问题 :**

-   确认正在运行的 Metabase 实例
-   检查网络连接
-   使用 HTTPS 验证 SSL 证书

**工具执行出错 :**

-   检查您的用户/ API 密钥的 Metabase 权限
-   验证请求的资源存在
-   详细错误消息审查服务器日志

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40cognitionai/metabase-mcp-server/LICENSE) 详细文件.

## 捐款

欢迎捐款! 请来看我们 [GitHub 仓库](https://github.com/CognitionAI/metabase-mcp-server) 改为:

-   报告错误
-   请求特性
-   提交拉动请求
-   \* 改进文件编制

### 发展指导方针

1.  叉子存储器
2.  创建特性分支
3.  用测试来改变
4.  确保所有测试通过
5.  提交拉动请求

## ++ 辅助

-   📚 [文档](https://github.com/CognitionAI/metabase-mcp-server/wiki)
-   🐛 [问题跟踪器](https://github.com/CognitionAI/metabase-mcp-server/issues)

* * *

与"为世界而建"

## 常见问题

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

Metabase 集成的示范背景协议服务器

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

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

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

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

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

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

### @cognitionai/metabase-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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