使用说明

元数据库MCP服务器

A. 元数据库的模型上下文协议（MCP）服务器 这使AI助手可以完全访问您的分析平台——仪表板、卡片、数据库、表格、集合等。

由开发和维护 EaseCloud --云原生、人工智能驱动和数据基础设施解决方案。

快速开始

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
表管理	17
收藏、用户和搜索	13
架构缓存（SQL→MBQL）	2

支持的元数据库版本

元数据库v0.46.x及以上版本（推荐：v0.48.x或更高版本）
元数据库云（完全支持）
自托管实例（Docker、JAR或云部署）

安装

npx（推荐）

npx @easecloudio/mcp-metabase-server

全局安装

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

码头工人

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密钥（首选）：

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

用户名/密码（回退）：

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`	所有工具，包括创建/更新/删除

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

Claude桌面集成

MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%/Claude/claude_desktop_config.json

使用npx：

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

使用工具过滤：

{
  "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"
      }
    }
  }
}

使用本地构建：

{
  "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"
      }
    }
  }
}

用户名/密码回退：

{
  "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 Management (27 tools)

核心CRUD

工具	说明
`list_dashboards`	列出所有仪表板
`get_dashboard`	按ID获取特定仪表板
`create_dashboard`	创建新仪表板
`update_dashboard`	更新现有仪表板
`delete_dashboard`	删除/存档仪表板
`copy_dashboard`	复制仪表板（浅拷贝或深拷贝）
`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`	更新特定dashcard的属性
`execute_dashboard_card`	执行特定的dashcard并返回结果

公共共享与嵌入

工具	说明
`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的所有卡查询

Card / Question Management (21 tools)

核心CRUD

工具	说明
`list_cards`	列出所有问题/卡片
`get_card`	按ID获取卡片（包括完整的SQL/MBQL查询）
`create_card`	创建新问题
`update_card`	更新现有问题
`delete_card`	删除/存档问题
`copy_card`	复制卡片
`move_cards`	将一张或多张卡片移动到其他集合
`move_cards_to_collection`	从源集合批量移动卡片

执行和导出

工具	说明
`execute_card`	运行卡片并返回结果
`execute_pivot_card_query`	运行格式化为透视表的卡
`export_card_result`	将结果导出为CSV或JSON

参数

工具	说明
`get_card_param_values`	获取卡参数的可用值
`search_card_param_values`	搜索/筛选参数值
`get_card_param_remapping`	获取参数值如何重新映射以进行显示

元数据和发现

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

公共共享与嵌入

工具	说明
`create_card_public_link`	创建公共共享链接
`delete_card_public_link`	删除公共链接
`list_public_cards`	列出带有公共链接的卡片
`list_embeddable_cards`	已启用嵌入的列表卡

Database Management (16 tools)

核心CRUD

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

询问

工具	说明
`execute_query`	对数据库执行SQL查询

架构与同步

工具	说明
`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`	测试现有连接

Table Management (17 tools)

元数据

工具	说明
`list_tables`	列表表（可选按数据库筛选）
`get_table`	按ID获取表元数据
`get_table_metadata`	获取完整的查询元数据，包括字段ID和类型
`get_table_fks`	获取外键关系
`get_table_related`	通过FK关系查找相关表
`get_table_data`	从表中获取示例数据预览
`get_field_id`	通过表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上传（元数据库管理的表）

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

Collections, Users & Search (13 tools)

集合

工具	说明
`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`	在所有元数据库内容中搜索

Schema Cache — SQL to MBQL (2 tools)

这些工具使人工智能能够将原生SQL问题转换为交互式MBQL问题。元数据库没有用于此转换的REST API-它需要字段ID，这些工具将这些字段ID缓存在本地。

它是如何工作的：

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

缓存存储在 ~/.easecloud/metabase-mcp/cache/{url-hash}/ 具有24小时TTL和每个Metabase实例的作用域。

工具	说明
`get_schema_cache`	返回缓存的架构（丢失或过时时自动获取）
`refresh_schema_cache`	强制刷新一个或所有数据库的缓存

MCP资源

直接通过以下方式访问元数据库实体 metabase:// URI：

URI	描述
`metabase://dashboard/{id}`	仪表板详细信息
`metabase://card/{id}`	卡片/问题详细信息
`metabase://database/{id}`	数据库信息
`metabase://collection/{id}`	收藏详情
`metabase://user/{id}`	用户信息
`metabase://table/{id}`	表元数据
`metabase://field/{id}`	现场信息

发展

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检查员:

npm run inspector

Inspector提供了一个浏览器UI，用于发送工具调用和检查响应。

关于易云

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

云原生应用开发
人工智能和自动化集成
DevOps和基础设施管理
数据分析和BI平台咨询

我们构建这个项目是为了为开源MCP生态系统做出贡献，同时展示我们在集成、自动化和云解决方案方面的专业知识。

如果您的团队正在大规模采用Metabase或希望将AI与BI堆栈集成，联系 --我们为企业提供咨询、定制和管理支持。

📧 support@easecloud.io 🌐 easecloud.io

Bug报告和问题

发现错误或有功能请求？

🐛 创建GitHub问题

请包括：

元数据库版本
MCP服务器版本
重现步骤
预期行为与实际行为
任何错误消息或日志

贡献

欢迎捐款。访问 GitHub存储库提交问题或拉取请求。

许可证

麻省理工学院——见许可证了解详情。

使用说明

元数据库MCP服务器

快速开始

96种可用工具

支持的元数据库版本

安装

npx（推荐）

全局安装

码头工人

配置

认证

工具筛选（Tool_MODE）

Claude桌面集成

可用工具

核心CRUD

卡片布局

公共共享与嵌入

修订、审核和发现

核心CRUD

执行和导出

参数

元数据和发现

公共共享与嵌入

核心CRUD

询问

架构与同步

诊断

元数据

卡片虚拟桌

管理

CSV上传（元数据库管理的表）

集合

用户

权限

搜索

MCP资源

发展

调试

关于易云

Bug报告和问题

贡献

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

文件与终端管理MCP服务

MCP 协议测试服务器

图表生成MCP服务器

Flomo笔记服务