内容
<p align="center">
<a href="https://github.com/dhavanikgithub/chartbrew-mcp">
<img src="assets/dark/chartbrew-mcp-banner.svg" alt="Chartbrew MCP 服务器">
</a>
</p>
<p align="center">
<strong>
<a href="https://github.com/dhavanikgithub/chartbrew-mcp">Chartbrew MCP 服务器</a> 公开 <a href="https://docs.chartbrew.com/api-reference/introduction">Chartbrew</a> 的文档化 API，供 AI 编码代理和 MCP 兼容的客户端使用 — 让它们可以列出和检查团队、连接、数据集、仪表板和图表，运行实时查询、获取数据、管理共享策略/令牌以实现安全嵌入，以及通过自然语言创建或更新资源。
</strong>
</p>
# Chartbrew MCP 服务器
使用官方 MCP SDK 构建的 TypeScript MCP 服务器，用于 Chartbrew API 端点的文档化。
<p align="center">
<a href="https://github.com/chartbrew/chartbrew">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/dark/chartbrew-logo.svg">
<source media="(prefers-color-scheme: light)" srcset="assets/light/chartbrew-logo.svg">
<img alt="Chartbrew 文档" src="assets/dark/chartbrew-logo.svg" height="30">
</picture>
</a>
</p>
<p align="center">
<a href="https://docs.chartbrew.com/api-reference/introduction">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/dark/chartbrew-docs-logo.png">
<source media="(prefers-color-scheme: light)" srcset="assets/light/chartbrew-docs-logo.png">
<img alt="Chartbrew 文档" src="assets/dark/chartbrew-docs-logo.png" height="20">
</picture>
</a>
</p>
## 展示
<p align="center">
<em>Chartbrew MCP 服务器在行动 — 通过自然语言管理分析资源。</em>
</p>
<table>
<tr>
<td align="center"><img src="assets/dark/Chartbrew-MCP-001.png" alt="Chartbrew MCP 服务器截图 1" width="400"></td>
<td align="center"><img src="assets/dark/Chartbrew-MCP-002.png" alt="Chartbrew MCP 服务器截图 2" width="400"></td>
<td align="center"><img src="assets/dark/Chartbrew-MCP-003.png" alt="Chartbrew MCP 服务器截图 3" width="400"></td>
</tr>
<tr>
<td align="center"><img src="assets/dark/Chartbrew-MCP-004.png" alt="Chartbrew MCP 服务器截图 4" width="400"></td>
<td align="center"><img src="assets/dark/Chartbrew-MCP-005.png" alt="Chartbrew MCP 服务器截图 5" width="400"></td>
<td align="center"><img src="assets/dark/Chartbrew-MCP-006.png" alt="Chartbrew MCP 服务器截图 6" width="400"></td>
</tr>
</table>
## 先决条件
- **Node.js** 和 **npm** 已安装（用于安装依赖项和构建服务器）。
- 一个 **Chartbrew API 密钥** — 在您的 Chartbrew 帐户（云或自托管）中创建。参见 [如何在 Chartbrew 中创建 API 密钥](https://chartbrew.com/blog/how-to-create-api-keys-in-chartbrew)。
- 对于自托管的 Chartbrew 实例，其 API 基本 URL（默认为 `http://localhost:4019`）。
- 一个 **MCP 兼容的客户端** 来托管服务器（例如 Claude Code、Claude Desktop、Cursor、VS Code、Codex、GitHub Copilot、OpenCode、Kimi Code）。
## 范围
此服务器仅实现官方 [Chartbrew API](https://docs.chartbrew.com/api-reference/introduction) 参考中记录的操作，避免未记录的行为。
已实现资源：
- 团队：列出，获取
- 连接：列出，获取，测试，创建，更新，删除
- 数据集：列出，获取，获取数据，创建，更新，删除
- 数据请求：列出，运行
- 仪表板（项目）：列出，获取，创建，更新，删除
- 图表：获取，创建，查询，删除
当前版本未实现：
- 变量绑定创建/更新端点
如果需要，可以稍后添加这些。
## 身份验证
Chartbrew API 文档指定了 Bearer 令牌身份验证。
此服务器使用的必需标头：
- 授权：Bearer <CHARTBREW_API_KEY>
## 配置选项
| 变量 | 描述 | 必需 |
| --- | --- | --- |
| `CHARTBREW_API_KEY` | 用于 Bearer 令牌身份验证的 Chartbrew API 密钥 | 是 |
| `CHARTBREW_API_BASE_URL` | API 基本 URL。对于官方 Chartbrew 云帐户，请使用 `https://api.chartbrew.com`；对于自托管实例，请使用您的实例 URL（默认为 `http://localhost:4019`；如果您的端口不同，请更改） | 否（默认为 `https://api.chartbrew.com`） |
| `CHARTBREW_REQUEST_TIMEOUT_MS` | 请求超时毫秒数，以防止请求挂起 | 否（默认为 `30000`） |
| `CHARTBREW_TOOL_MODE` | 工具暴露模式。允许的值：`restricted`，`unrestricted`。如果未设置或设置为除 `unrestricted` 之外的任何值，则服务器以 `restricted` 模式运行 | 否（默认为 `restricted`） |
工具模式行为：
- 无限制：所有已实现的工具都可用。
- 限制：仅限数据检索/查询工具可用（列出/获取/获取/查询/运行/测试）。创建/更新/删除工具被禁用。
您可以按以下两种方式之一提供这些值（请选择一种）：
- **此 `mcp` 文件夹中的 `.env` 文件** — 复制 `.env-template` 到 `.env` 并填写值。服务器在启动时自动加载它。
- **编码代理的 MCP 配置的 `env` 块** — 直接在服务器条目的 `env` 对象中设置变量（例如 Claude Code 的 `.mcp.json` 或 Codex、GitHub Copilot、OpenCode、Kimi Code 等的等效 MCP 配置）。当您不想使用本地 `.env` 文件时，请使用此方法。
## 安装
1. 切换到 `mcp` 目录。
2. 安装依赖项：
```bash
npm install
```
3. 构建：
```bash
npm run build
```
4. 运行
```bash
npm start
```
服务器使用 stdio 传输，旨在由 MCP 客户端主机启动。
## 独立二进制文件（无需 Node.js）
如果您不想安装 Node.js，可以从 [Releases](https://github.com/dhavanikgithub/chartbrew-mcp/releases) 页面下载预构建的二进制文件并直接运行。提供以下二进制文件：
| 操作系统 | x64（Intel/AMD） | arm64（Apple Silicon / ARM） |
| --- | --- | --- |
| Windows | `chartbrew-mcp-windows-x64.exe` | `chartbrew-mcp-windows-arm64.exe` |
| Linux | `chartbrew-mcp-linux-x64` | `chartbrew-mcp-linux-arm64` |
| macOS | `chartbrew-mcp-darwin-x64` | `chartbrew-mcp-darwin-arm64` |
**设置：**
发布版本包括原始二进制文件和压缩存档（Windows 使用 `.zip`，Linux/macOS 使用 `.tar.gz`）— 获取存档以获得较小的下载文件，然后提取它。
- **Windows：** 下载 `chartbrew-mcp-windows-x64.zip`（或 `arm64`），提取并运行 `.exe` 文件。
- **macOS / Linux：** 下载例如 `chartbrew-mcp-darwin-arm64.tar.gz`，提取并使其可执行一次：`chmod +x chartbrew-mcp-darwin-arm64`
- **macOS Gatekeeper：** 如果 macOS 阻止未签名的二进制文件，请删除隔离属性：`xattr -d com.apple.quarantine chartbrew-mcp-darwin-arm64`
您 **不需要** `.env` 文件 — 通过 MCP 客户端的 `env` 块（或操作系统环境）设置配置。例如适用于 Claude Desktop / Claude Code（`.mcp.json` 或 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"chartbrew": {
"command": "/absolute/path/to/chartbrew-mcp-darwin-arm64",
"env": {
"CHARTBREW_API_KEY": "your-api-key",
"CHARTBREW_API_BASE_URL": "https://api.chartbrew.com",
"CHARTBREW_TOOL_MODE": "restricted"
}
}
}
}
```
### 自己构建二进制文件
从检出开始，安装 [Bun](https://bun.sh)（编译器），然后：
```bash
npm install
npm run build:bin # 将二进制文件写入 dist-bin/
```
完整的设置、Bun 安装命令和 Windows 跨编译注意事项都在 [CONTRIBUTING.md](./CONTRIBUTING.md#building-standalone-binaries) 中。
## 添加到 MCP 客户端
在 `npm install` 和 `npm run build` 之后，使用您的 MCP 主机注册服务器。服务器通过 `node dist/index.js` 运行在 stdio 上。将 `<ABSOLUTE_PATH_TO_MCP_DIR>` 替换为此 `mcp` 目录的绝对路径，并设置您的 API 密钥。
### Claude Code CLI（`claude mcp add`）
如果您使用 Claude Code，可以直接从终端注册服务器，而无需编辑配置文件：
```bash
claude mcp add chartbrew \
-e CHARTBREW_API_KEY=your-api-key \
-e CHARTBREW_API_BASE_URL=https://api.chartbrew.com \
-e CHARTBREW_TOOL_MODE=restricted \
-- node <ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js
```
- 自托管实例使用 `http://localhost:4019` 作为 `CHARTBREW_API_BASE_URL`（如果您的端口不同，请更改）。
- 添加 `-s user`（或 `-s project`）以控制服务器注册的作用域。
- 通过 `claude mcp list` 验证；通过 `claude mcp remove chartbrew` 删除。
### Claude Desktop / Claude Code（`claude_desktop_config.json` 或 `.mcp.json`）
```json
{
"mcpServers": {
"chartbrew": {
"command": "node",
"args": ["<ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js"],
"env": {
"CHARTBREW_API_KEY": "your-api-key",
"CHARTBREW_API_BASE_URL": "https://api.chartbrew.com",
"CHARTBREW_TOOL_MODE": "unrestricted"
}
}
}
}
```
### Cursor / VS Code（设置 UI → MCP 服务器）
```json
{
"mcpServers": {
"chartbrew": {
"command": "node",
"args": ["<ABSOLUTE_PATH_TO_MCP_DIR>/dist/index.js"],
"env": {
"CHARTBREW_API_KEY": "your-api-key"
}
}
}
}
```
> **API 基本 URL：** 对于官方 Chartbrew 云帐户，请使用 `https://api.chartbrew.com`。对于自托管实例，请使用您的本地 URL — 默认 `http://localhost:4019`（如果您的端口不同，请更改）。
注意：
- 需要 `CHARTBREW_API_KEY`。参见 [如何在 Chartbrew 中创建 API 密钥](https://chartbrew.com/blog/how-to-create-api-keys-in-chartbrew)。
- MCP 主机启动服务器；无需手动运行它。
- 默认工具模式为 `restricted`（仅限读取/查询）。设置 `CHARTBREW_TOOL_MODE: "unrestricted"` 以启用创建/更新/删除工具。
- 或者，在 `mcp` 目录中设置环境变量到 `.env` 文件中并省略 `env` 块。
## 可用工具
| 工具 | 类别 | 描述 |
| --- | --- | --- |
| `chartbrew_teams_list` | 团队 | 列出可用于身份验证的 API 密钥的团队 |
| `chartbrew_teams_get` | 团队 | 通过 `team_id` 获取团队详细信息 |
| `chartbrew_teams_create` | 团队 | 创建一个新团队；所有者源自身份验证的 API 密钥 |
| `chartbrew_teams_update` | 团队 | 更新现有团队通过 `team_id` |
| `chartbrew_connection_providers_list` | 连接 | 列出所有支持的连接提供程序 |
| `chartbrew_connections_schema_get` | 连接 | 获取特定连接的模式结构 |
| `chartbrew_connections_list` | 连接 | 列出团队中的所有连接 |
| `chartbrew_connections_get` | 连接 | 通过 `connection_id` 获取一个连接 |
| `chartbrew_connections_test` | 连接 | 为团队连接运行 Chartbrew 连接测试 |
| `chartbrew_connections_create` | 连接 | 在团队中创建一个新连接 |
| `chartbrew_connections_update` | 连接 | 更新现有连接 |
| `chartbrew_connections_update_files` | 连接 | 通过 multipart 上传 SSL CA/证书/密钥文件（base64）- 用于 PostgreSQL/MySQL SSL/TLS 身份验证 |
| `chartbrew_connections_delete` | 连接 | 删除连接；可选删除链接的数据集 |
| `chartbrew_datasets_list` | 数据集 | 列出团队的数据集 |
| `chartbrew_datasets_get` | 数据集 | 通过 `dataset_id` 获取一个数据集 |
| `chartbrew_datasets_fetch_data` | 数据集 | 运行数据集请求并返回数据集数据 |
| `chartbrew_datasets_create` | 数据集 | 在团队中创建一个新的数据集 |
| `chartbrew_datasets_quick_create` | 数据集 | 在单个调用中创建一个数据集及其所有数据请求 |
| `chartbrew_datasets_update` | 数据集 | 通过 `dataset_id` 更新现有数据集 |
| `chartbrew_datasets_delete` | 数据集 | 删除数据集 |
| `chartbrew_data_requests_list` | 数据请求 | 列出数据集的数据请求 |
| `chartbrew_data_requests_run` | 数据请求 | 执行数据集数据请求 |
| `chartbrew_dashboards_list` | 仪表板 | 列出团队的仪表板 |
| `chartbrew_dashboards_get` | 仪表板 | 通过 `project_id` 获取仪表板详细信息 |
| `chartbrew_dashboards_create` | 仪表板 | 创建一个新仪表板（项目）；默认为私有 |
| `chartbrew_dashboards_update` | 仪表板 | 通过 `project_id` 更新现有仪表板 |
| `chartbrew_dashboards_delete` | 仪表板 | 通过 `project_id` 删除仪表板 |
| `chartbrew_dashboards_create_share_policy` | 仪表板 | 为安全共享创建共享策略，通过签名 URL |
| `chartbrew_dashboards_update_share_policy` | 仪表板 | 更新仪表板共享策略（参数，`allow_params`，过期） |
| `chartbrew_dashboards_delete_share_policy` | 仪表板 | 删除仪表板的共享策略 |
| `chartbrew_dashboards_generate_share_token` | 仪表板 | 为安全嵌入生成签名的 JWT |
| `chartbrew_charts_get` | 图表 | 通过 `project_id` 和 `chart_id` 获取图表 |
| `chartbrew_charts_create` | 图表 | 在仪表板项目中创建一个图表 |
| `chartbrew_charts_quick_create` | 图表 | 在单个调用中创建一个图表及其图表数据集配置 |
| `chartbrew_chart_dataset_configs_create` | 图表 | 通过 `ChartDatasetConfig` 将数据集附加到图表 |
| `chartbrew_chart_dataset_configs_update` | 图表 | 通过 `cdc_id` 更新现有的 `ChartDatasetConfig` |
| `chartbrew_chart_dataset_configs_delete` | 图表 | 通过 `cdc_id` 删除 `ChartDatasetConfig` |
| `chartbrew_charts_query` | 图表 | 运行图表查询端点并返回结果数据 |
| `chartbrew_charts_delete` | 图表 | 通过 `project_id` 和 `chart_id` 删除图表 |
| `chartbrew_charts_create_share_policy` | 图表 | 为安全嵌入创建图表的共享策略 |
| `chartbrew_charts_update_share_policy` | 图表 | 更新图表共享策略（参数，`allow_params`，过期） |
| `chartbrew_charts_delete_share_policy` | 图表 | 删除图表的共享策略 |
| `chartbrew_charts_generate_share_token` | 图表 | 为安全嵌入生成签名的 JWT |
## 已知文档限制反映在实现中
- ID 类型在文档中不一致（数字 vs 字符串），因此工具输入接受字符串。
- 一些 create/update 有效载体所需字段未一致记录，因此有效载体类型为灵活对象。
- 数据集获取过滤器查询对象编码未记录；此服务器发送对象值作为 JSON 字符串。
- 错误响应模式因端点而异；解析器在可用时处理 error 和 message 字段。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器