内容
# metabase-mcp
使用 AI 代理查询 Metabase，无需 API 密钥，无需管理员许可。只需轻松操作和一个 cookie。
---
## 问题
官方 Metabase MCP 需要 API 密钥或用户名/密码。理论上听起来不错，但如果公司不愿意给你呢？
但是，你 *可以* 在浏览器中登录 Metabase。这意味着你拥有一个会话 cookie。这意味着你拥有所需的一切。
这就是我们的目的。
## 等一下，我应该使用这个吗？
诚实的答案：**如果你有 API 密钥或用户名/密码，请直接使用官方 Metabase MCP**。它正规、受支持，并且不会在对话中途过期。较新版本的 Metabase 还支持通过官方 MCP 进行 Google 登录。
这个项目是为我们其他人准备的：那些公司像核发射密码一样保管 API 密钥，并且将每个 Metabase 升级请求视为 6 个月的采购流程的人。
**你会喜欢这个项目，如果：**
- 您的组织控制 Metabase，但您没有浏览器登录凭证以外的权限
- 您的 Metabase 版本尚不支持官方 MCP 的 Google 登录
- 您更愿意从 DevTools 中提取 cookie，而不是编写另一个 Jira 工单
- 您想使用 AI 查询数据并继续您的生活
**您应该知道：**
| 优点 | 缺点 |
|---|---|
| 只需浏览器登录即可使用 | cookie 会过期，您需要偶尔重新粘贴 |
| 继承您确切的 Metabase 权限 | 如果使用会话文件，令牌以明文存储在磁盘上（可选，您可以改为内联传递） |
| 在 Metabase 端无需设置 | 如果您的会话注销，MCP 也会注销 |
## 功能
| 工具 | 功能 |
|---|---|
| `list_databases` | 列出所有连接的数据库 |
| `list_collections` | 列出所有集合（文件夹） |
| `list_collection_items` | 列出集合中的问题、仪表板和子集合 |
| `list_cards` | 列出所有已保存的问题 |
| `get_card` | 获取特定问题的详细信息 |
| `create_card` | 在集合中创建新的已保存问题 |
| `run_card` | 执行已保存的问题并返回结果 |
| `list_dashboards` | 列出所有仪表板 |
| `get_dashboard` | 获取带有卡片布局的仪表板 |
| `list_tables` | 列出表格，可选按数据库筛选 |
| `search` | 跨问题、仪表板、集合和表格搜索 |
| `execute_query` | 对任何连接的数据库运行临时查询 |
## 先决条件
- Go 1.25.5+
- 一个您可以登录的 Metabase 实例
## 安装
```bash
go install github.com/Naveen-chava/metabase-mcp@latest
```
这会将二进制文件放入 `~/go/bin/`。确保它在您的 `$PATH` 中：
```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```
**或从源代码构建：**
```bash
git clone https://github.com/Naveen-chava/metabase-mcp
cd metabase-mcp
go install .
```
## 获取会话 cookie
这是一个稍微有点 tricky 的步骤。
1. 在浏览器中打开 Metabase 并登录
2. 打开 DevTools → **应用程序** → **cookie** → 选择您的 Metabase 域名
3. 找到 `metabase.SESSION` 并复制其值
这就是您的 cookie。请像对待密码一样保护它；它授予的权限与您的登录会话相同。
> 如果 MCP 开始抛出 401 错误，您的会话已过期。获取一个新的 cookie，您就可以继续使用了。
## 配置
| 变量 | 必需 | 描述 |
|---|---|---|
| `METABASE_URL` | 是 | 您的 Metabase 实例的基本 URL |
| `METABASE_SESSION` | 以下两者之一 | 会话 cookie 值，在启动时读取一次 |
| `METABASE_SESSION_FILE` | 以下两者之一 | 包含 cookie 的文件路径，每次请求时读取，以便轮换只需覆盖文件 |
**内联（快速启动）：**
```bash
METABASE_URL=https://metabase.company.com \
METABASE_SESSION=your-cookie \
./metabase-mcp
```
**通过文件（推荐，当 cookie 过期时无需重启）：**
```bash
echo "your-cookie" > ~/.metabase-session
METABASE_URL=https://metabase.company.com \
METABASE_SESSION_FILE=~/.metabase-session \
./metabase-mcp
```
要轮换过期的 cookie，只需覆盖文件。无需重启；下一个请求会自动获取新的 cookie。
> 服务器扩展了 `~` 和 `$HOME` 在会话文件路径中，因此 `~/.metabase-session` 在任何地方都有效。
## Claude 桌面版
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"metabase": {
"command": "metabase-mcp",
"env": {
"METABASE_URL": "https://metabase.company.com",
"METABASE_SESSION_FILE": "~/.metabase-session"
}
}
}
}
```
重启 Claude 桌面版。完成。
## Claude 代码
```bash
claude mcp add metabase metabase-mcp -s user -e METABASE_URL=https://metabase.company.com -e METABASE_SESSION_FILE=~/.metabase-session
```
> 运行为单行。反斜杠延续可能会在复制某些终端或浏览器时引入不可见字符。
## 光标
添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目级）：
```json
{
"mcpServers": {
"metabase": {
"command": "metabase-mcp",
"env": {
"METABASE_URL": "https://metabase.company.com",
"METABASE_SESSION_FILE": "~/.metabase-session"
}
}
}
}
```
重启 Cursor 并在 **设置 → MCP** 下验证服务器已连接。
## 示例提示
- _"Metabase 连接了哪些数据库？"_
- _"显示 Analytics DB 中的所有表格"_
- _"我的个人收藏中有什么？"_
- _"运行 '每日活跃用户' 问题"_
- _"搜索与收入相关的任何内容"_
- _"在 Analytics DB 上运行此 SQL：SELECT count(\*) FROM orders WHERE created\_at > now() - interval 7 day"_
- _"查询 MongoDB 中的订单集合，并按类别分组收入"_
- _"创建一个显示按支出排名前列的客户的已保存问题"_
## 项目结构
```
metabase-mcp/
├── main.go # 启动，环境变量，将所有内容连接起来
└── internal/
├── metabase/ # Metabase API 客户端
│ ├── client.go # 带有 cookie 身份验证的 HTTP 客户端
│ ├── types.go # API 类型
│ ├── databases.go
│ ├── collections.go
│ ├── cards.go
│ ├── dashboards.go
│ ├── tables.go
│ ├── search.go
│ ├── query.go
│ └── tests/ # HTTP 级测试（包 metabase_test）
└── tools/ # MCP 工具处理程序
├── client.go # MetabaseClient 接口
├── register.go # 一个地方添加/删除工具
├── helpers.go # 共享实用程序
├── databases.go
├── collections.go
├── cards.go
├── dashboards.go
├── tables.go
├── search.go
├── query.go
└── tests/ # 带有模拟客户端的处理程序测试（包 tools_test）
```
## 运行测试
```bash
go test ./...
```
