自述文件：Metabase MCP Server

一个全面的 Model Context Protocol (MCP) 服务器，用于 Metabase 集成，为 AI 助手提供对 Metabase 分析平台的完整访问权限。

🚀 快速开始

# 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

Related MCP server: Metabase MCP Server

✨ 功能特性

🎯 81+ 个可用工具 - 完整覆盖 Metabase API

• 📊 仪表板管理（23 个工具）- 完整的增删改查操作、卡片管理、公开共享、嵌入

• 📈 卡片/问题管理（21 个工具）- 查询执行、参数处理、透视查询、公开链接

• 🗄️ 数据库管理（13 个工具）- 连接管理、模式同步、查询执行

• 📋 表管理（16 个工具）- 元数据操作、字段管理、数据操作

• 🔍 其他工具（9 个工具）- 集合、搜索、用户、活动跟踪、Playground 链接

📦 安装

💡 建议： 使用 Node.js 20.19.0+ 和 npm 8.0.0+ 以获得最佳兼容性

方法 1：NPX（推荐）

npx @cognitionai/metabase-mcp-server

方法 2：全局安装

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

方法 3：Docker

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

⚙️ 配置

环境变量

API 密钥身份验证（首选）：

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

用户名/密码身份验证（备用）：

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

可选参数

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

• --essential（默认）：仅加载基础工具

• --all：加载全部 80+ 个可用工具

• --write：仅加载写入/修改类工具

• --read：仅加载只读工具

# 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 Desktop

在你的 Claude Desktop 配置中添加（macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

使用本地开发构建：

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

使用自定义标志：

{
  "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）：

使用已发布包：

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

使用本地开发构建：

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

使用自定义标志：

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

🛠️ 可用工具

核心操作

• list_dashboards - 列出所有仪表板

• get_dashboard - 按 ID 获取仪表板

• 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 - 获取仪表板项目

核心操作

• list_cards - 列出所有卡片/问题

• get_card - 按 ID 获取卡片

• 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 - 列出可嵌入卡片

核心操作

• list_databases - 列出所有数据库

• get_database - 获取数据库详情

• create_database - 创建数据库连接

• update_database - 更新数据库设置

• delete_database - 删除数据库连接

模式与元数据

• 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 - 重新扫描字段值

核心操作

• list_tables - 带筛选条件列出表

• get_table - 获取表详情

• update_table - 更新表配置

• update_tables - 批量更新表

数据操作

• get_table_data - 检索表数据

• append_csv_to_table - 追加 CSV 数据

• replace_table_csv - 用 CSV 数据替换

模式与关系

• 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 - 获取卡片表元数据

集合

• list_collections - 列出所有集合

• create_collection - 创建新集合

• update_collection - 更新集合

• delete_collection - 删除集合

• get_collection_items - 获取集合项目

搜索与发现

• search_content - 搜索所有内容

活动与分析

• get_recent_views - 获取最近活动

• get_popular_items - 获取热门内容

Playground 链接

• get_metabase_playground_link - 生成交互式 Playground 链接

🧪 开发

环境搭建

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

构建

npm run build

开发模式

npm run watch

调试

使用 MCP Inspector 进行调试：

npm run inspector

🔍 测试身份验证

API 密钥身份验证

1. 设置 METABASE_URL 和 METABASE_API_KEY

2. 启动服务器，并在日志中确认 "Using Metabase API Key"

3. 使用 list_dashboards 工具进行测试

用户名/密码身份验证

1. 取消设置 METABASE_API_KEY

2. 设置 METABASE_URL、METABASE_USERNAME、METABASE_PASSWORD

3. 启动服务器，并在日志中确认 "Using username/password"

4. 使用 list_dashboards 工具进行测试

🐛 故障排除

常见问题

身份验证错误：

• 确认你的 Metabase URL 可访问

• 在 Metabase 管理员设置中检查 API 密钥的有效性

• 确保用户名/密码凭据正确

连接问题：

• 确认 Metabase 实例正在运行

• 检查网络连通性

• 如果使用 HTTPS，请验证 SSL 证书

工具执行错误：

• 检查你的用户/API 密钥在 Metabase 中的权限

• 确认所请求的资源存在

• 查看服务器日志以获取详细的错误信息

📄 许可证

本项目使用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！请访问我们的 GitHub 仓库 来：

• 🐛 报告 Bug

• 💡 请求新功能

• 🔧 提交 Pull Request

• 📖 改进文档

开发指南

1. Fork 本仓库

2. 创建功能分支

3. 进行修改并添加测试

4. 确保所有测试通过

5. 提交 Pull Request

🆘 支持

• 📚 文档

• 🐛 问题跟踪器

用 ❤️ 为世界构建