内容
# WACM 连接 MCP 服务器
适用于 [Wasabi WACM Connect API](https://docs.wasabi.com/docs/wacm-connect-api) 的[模型上下文协议（MCP）](https://modelcontextprotocol.io)服务器。开箱即提供 18 种只读工具，并通过分级访问控制提供 12 种可选的写工具。为需要通过 Claude 管理其 Wasabi 账户层次结构、存储使用情况和计费数据的托管服务提供商（MSP）设计。
> [!WARNING]
> **此 MCP 服务器对您的 Wasabi 账户管理基础设施具有写访问权限。**
>
> 此工具可以创建、修改和删除您实时 WACM 环境中的子账户、成员、渠道账户和其他资源。**通过此 MCP 执行的操作是真实的，可能不可逆转。**
## 免责声明
这是一个独立的、社区维护的项目。**它与 Wasabi Technologies 无关，不受其支持或认可**。“Wasabi”和“WACM”是 Wasabi Technologies, Inc. 的商标。Wasabi Technologies 不对通过此集成进行的意外更改负责。
### 与 AI 相关的风险
此服务器设计用于由 AI 助手（LLM）操作。AI 模型可能会出错 - 它们可能会误解指令、幻觉参数值或执行您未打算的操作。在账户管理的背景下，这意味着 AI 可能会意外地：
- **创建不想要的账户**，具有不正确的配置或存储配额
- **修改现有的账户**，更改您不想更改的设置、角色或权限
- **删除不应该删除的账户、成员或渠道账户**
- **对多个资源执行批量操作**，当您打算进行单个更改时
- **对错误资源采取行动**，混淆类似命名的账户或 ID
这些是针对您的真实 Wasabi 基础设施的真实 API 调用，除非您使用的是专用的测试账户。AI 和您的环境之间没有沙盒、预发布层或撤销按钮。
### 使用前
- **了解您的 API 凭证** - API 密钥的权限范围决定了 AI 可以访问的内容
- **在非生产环境中测试**，如果可能，在启用生产账户的写访问权限之前
- **以只读模式启动** - 写工具默认禁用；仅启用您需要的最低级别
- **使用干运行模式** - 每个写工具都支持 `dryRun: true`，以预览执行前的确切 HTTP 请求
- **在确认之前审查所有 AI 建议的操作**，尤其是批量操作或删除操作
- **优先使用操作允许列表**，而不是广泛的层级访问，以将暴露限制在您实际需要的工具上
### 责任
**自担风险使用。** 作者不对数据丢失、服务中断、意外账户修改或其他因使用此软件而导致的损害承担责任 - 无论是由 AI 错误、配置错误还是其他原因引起的。请参阅 [Apache 2.0 许可证](LICENSE) 以获取完整条款。
## 先决条件
- **Node.js 24+** （使用原生 `fetch`）
- **WACM Connect API 凭证** - 在 WACM 下的 **我的个人资料 > WACM Connect** 中生成 API 密钥（[Wasabi 文档](https://docs.wasabi.com/docs/generating-wacm-connect-api-keys)）
## 安装
```bash
git clone https://github.com/myst3k/wasabi-wacm-connect-mcp.git
cd wasabi-wacm-connect-mcp
pnpm install
pnpm build
```
## 配置
### Claude 代码（`.mcp.json`）
只读（默认）：
```json
{
"mcpServers": {
"wasabi-wacm-connect-mcp": {
"command": "node",
"args": ["/path/to/wasabi-wacm-connect-mcp/dist/index.js"],
"env": {
"WACM_USERNAME": "your-username",
"WACM_API_KEY": "your-api-key"
}
}
}
}
```
具有写访问权限（创建 + 更新）：
```json
{
"mcpServers": {
"wasabi-wacm-connect-mcp": {
"command": "node",
"args": ["/path/to/wasabi-wacm-connect-mcp/dist/index.js"],
"env": {
"WACM_USERNAME": "your-username",
"WACM_API_KEY": "your-api-key",
"WACM_WRITE_ACCESS": "true",
"WACM_WRITE_LEVEL": "manage"
}
}
}
}
```
仅限特定写操作：
```json
{
"mcpServers": {
"wasabi-wacm-connect-mcp": {
"command": "node",
"args": ["/path/to/wasabi-wacm-connect-mcp/dist/index.js"],
"env": {
"WACM_USERNAME": "your-username",
"WACM_API_KEY": "your-api-key",
"WACM_WRITE_ACCESS": "true",
"WACM_WRITE_ALLOWED_OPERATIONS": "create_sub_account,delete_member"
}
}
}
}
```
### Claude 桌面版（`claude_desktop_config.json`）
```json
{
"mcpServers": {
"wasabi-wacm-connect-mcp": {
"command": "node",
"args": ["/path/to/wasabi-wacm-connect-mcp/dist/index.js"],
"env": {
"WACM_USERNAME": "your-username",
"WACM_API_KEY": "your-api-key",
"WACM_WRITE_ACCESS": "true",
"WACM_WRITE_LEVEL": "full"
}
}
}
}
```
### 环境变量
| 变量 | 描述 | 必需 |
| --- | --- | --- |
| `WACM_USERNAME` | WACM Connect 用户名 | 是 |
| `WACM_API_KEY` | WACM Connect API 密钥 | 是 |
| `WACM_WRITE_ACCESS` | 设置为 `true` 以启用写操作（开关） | 否 |
| `WACM_WRITE_LEVEL` | 写访问级别：`create`、`manage` 或 `full`（见下文） | 否 |
| `WACM_WRITE_ALLOWED_OPERATIONS` | 以逗号分隔的启用写操作名称列表 | 否 |
CLI 标志 `--username` 和 `--api-key` 覆盖环境变量。
## 写访问级别
默认情况下，写操作被禁用。要启用它们，您必须设置 `WACM_WRITE_ACCESS=true` **和** `WACM_WRITE_LEVEL` 或 `WACM_WRITE_ALLOWED_OPERATIONS` 中的至少一个。开关（`WACM_WRITE_ACCESS`）必须显式设置 - 没有它，不管其他设置如何，都不会注册写工具。
| 级别 | 启用的工具 | 数量 |
| --- | --- | --- |
| `create` | 所有 5 个 POST（创建）工具 | 5 |
| `manage` | `create` + 3 个 PUT（更新）工具 | 8 |
| `full` | `manage` + 4 个 DELETE 工具 | 12 |
当同时设置两个环境变量时，解析的操作是两者的**并集**：
- `WACM_WRITE_LEVEL=manage` + `WACM_WRITE_ALLOWED_OPERATIONS=delete_member` → 9 个写工具
- `WACM_WRITE_ALLOWED_OPERATIONS=create_sub_account,delete_member`（无级别）→ 仅这两个
未知级别值或操作名称被记录为警告并被忽略。
### 有效操作名称
`create_sub_account`, `update_sub_account`, `delete_sub_account`, `create_member`, `update_member`, `delete_member`, `create_channel_account`, `update_channel_account`, `delete_channel_account`, `create_channel_account_user`, `delete_channel_account_user`, `create_standalone_account`
## 可用工具（最多 30 个）
### 控制账户（只读）
| 工具 | 描述 |
| --- | --- |
| `list_control_accounts` | 列出所有控制账户，及其存储分配和子账户数量 |
| `get_control_account` | 按 ID 获取特定控制账户 |
| `list_control_account_usages` | 列出聚合使用数据（存储、出口、进口、API 调用） |
| `get_control_account_usage` | 按利用率 ID 获取特定使用记录 |
| `list_control_account_buckets` | 列出控制账户的桶级利用率 |
### 子账户
| 工具 | 描述 | 访问权限 |
| --- | --- | --- |
| `list_sub_accounts` | 列出所有子账户（Wasabi 控制台账户） | 读取 |
| `get_sub_account` | 按 ID 获取特定子账户 | 读取 |
| `list_sub_account_buckets` | 列出子账户的桶级利用率 | 读取 |
| `create_sub_account` | 在控制账户下创建新子账户 | 写（`create`） |
| `update_sub_account` | 更新现有子账户 | 写（`manage`） |
| `delete_sub_account` | 删除子账户 | 写（`full`） |
### 渠道账户
| 工具 | 描述 | 访问权限 |
| --- | --- | --- |
| `list_channel_accounts` | 列出所有渠道账户（第三方访问层） | 读取 |
| `get_channel_account` | 按 ID 获取特定渠道账户 | 读取 |
| `create_channel_account` | 创建新渠道账户 | 写（`create`） |
| `update_channel_account` | 更新现有渠道账户 | 写（`manage`） |
| `delete_channel_account` | 删除渠道账户 | 写（`full`） |
### 渠道账户用户
| 工具 | 描述 | 访问权限 |
| --- | --- | --- |
| `create_channel_account_user` | 为渠道账户创建用户 | 写（`create`） |
| `delete_channel_account_user` | 删除渠道账户用户 | 写（`full`） |
### 成员
| 工具 | 描述 | 访问权限 |
| --- | --- | --- |
| `list_members` | 列出具有角色和 MFA 状态的子账户成员 | 读取 |
| `get_member` | 按 ID 获取特定成员 | 读取 |
| `create_member` | 在子账户中创建新成员 | 写（`create`） |
| `update_member` | 更新现有成员 | 写（`manage`） |
| `delete_member` | 删除成员 | 写（`full`） |
### 发票（只读）
| 工具 | 描述 |
| --- | --- |
| `list_invoices` | 列出具有子账户成本明细的发票 |
| `get_invoice` | 按 ID 获取特定发票 |
### 使用情况（只读）
| 工具 | 描述 |
| --- | --- |
| `list_usages` | 列出子账户级每日使用情况指标 |
| `get_usage` | 按利用率 ID 获取特定使用情况记录 |
### 独立账户
| 工具 | 描述 | 访问权限 |
| --- | --- | --- |
| `list_standalone_accounts` | 列出独立账户（不在 WACM 层次结构中） | 读取 |
| `get_storage_amounts` | 获取可用的存储量选项 | 读取 |
| `create_standalone_account` | 创建新独立账户 | 写（`create`） |
## 保障措施
写操作受到多个安全层的保护：
1. **开关** - 必须显式设置 `WACM_WRITE_ACCESS=true` 以启用任何写操作。没有它，所有其他写设置都被忽略，服务器严格为只读。
2. **分级访问控制** - `WACM_WRITE_LEVEL` 控制哪些类别的写工具被注册。未注册的工具对 LLM 完全不可见。
3. **操作允许列表** - `WACM_WRITE_ALLOWED_OPERATIONS` 提供对确切的写工具的细粒度控制，独立于或与层级结合使用。
4. **MCP 工具注释** - 每个写工具都带有元数据提示，供 LLM 使用：
- 创建（POST）：`readOnlyHint: false`
- 更新（PUT）：`readOnlyHint: false, idempotentHint: true`
- 删除（DELETE）：`readOnlyHint: false, destructiveHint: true`
5. **干运行模式** - 每个写工具都接受一个 `dryRun` 布尔参数（默认值：`false`）。当 `true` 时，工具返回 HTTP 请求的预览（方法、URL、标头、正文），而不执行它。身份验证凭证在预览中被遮蔽。
## 可用资源（4）
| 资源 | URI | 描述 |
| --- | --- | --- |
| 账户层次结构 | `wacm://hierarchy` | 4 层账户结构的 Markdown 文档 |
| 控制账户 | `wacm://control-accounts/{id}` | 控制账户详情的动态资源 |
| 子账户 | `wacm://sub-accounts/{id}` | 子账户详情的动态资源 |
| 国家/地区 | `wacm://reference/countries` | 可用的国家/地区代码 |
## 可用提示（5）
| 提示 | 描述 | 参数 |
| --- | --- | --- |
| `storage-summary` | 总结存储使用情况，突出接近配额的账户 | `controlAccountId`（可选） |
| `billing-report` | 按子账户划分的每月计费明细 | `from`, `to`, `controlAccountId`（可选） |
| `account-audit` | 审计层次结构中停用/不安全的账户 | `controlAccountId`（可选） |
| `usage-trend` | 分析子账户随时间变化的使用趋势 | `subAccountId`, `from`, `to` |
| `bucket-analysis` | 分析桶利用率，查找最大/最活跃的 | `accountId`, `accountType` |
## 示例对话
### 查看所有账户的存储
> "显示我所有控制账户的存储使用情况汇总"
Claude 将使用 `storage-summary` 提示调用 `list_control_accounts` 和 `list_sub_accounts`，然后呈现一个表格，比较活跃存储与配额。
### 调查每月成本
> "我上个月的费用是多少？按子账户划分"
Claude 将调用 `list_invoices` 以及上个月的日期范围，按子账户分组，确定成本最高的账户和类别。
### 安全审计
> "审计我的账户层次结构是否存在安全问题"
Claude 将使用 `account-audit` 提示枚举所有账户和成员，检查缺少 MFA、停用账户和配置错误的配额。
### 使用干运行创建子账户
> "在控制账户 5 下创建一个名为 'Acme Corp' 的新子账户 - 但首先显示请求"
Claude 将调用 `create_sub_account` 并设置 `dryRun: true`，并显示完整的 HTTP 请求预览。您确认后，它将执行实际请求。
## 故障排除
### 身份验证错误
- 验证您的凭证：`curl -u "$WACM_USERNAME:$WACM_API_KEY" https://api.wacm.wasabisys.com/api/v1/control-accounts`
- API 密钥仅在生成时显示一次 - 如果丢失，请重新生成
- 检查您使用的密钥类型（账户 API 密钥 vs 个人 API 密钥）
### 速率限制
- API 每秒允许 5 个 GET 请求，每个 API 密钥
- 客户端在 HTTP 429 响应时自动重试一次
- 对于批量操作，请使用内置速率限制器的自动节流
### 缺失数据
- 检查您的用户权限 - 可见性取决于您在账户层次结构中的层级
- Governance 用户查看所有账户；控制账户用户仅查看他们自己的账户
- 使用 `includeDeleted: true` 查看已删除的子账户
### 写工具未出现
- 验证您的 `WACM_WRITE_LEVEL` 或 `WACM_WRITE_ALLOWED_OPERATIONS` 是否已在 MCP 配置中设置
- 检查 stderr 中有关未知级别值或操作名称的警告消息
- 更改环境变量后重启 MCP 服务器
## 安全
- **凭证仅存储在内存中** - 绝不写入磁盘或日志
- **默认隐藏敏感字段** - `includeKeys` 和 `includeApiKey` 默认值为 `false`
- **写工具需选择加入** - 除非通过环境变量显式启用，否则不提供任何写操作
- **干运行预览会遮蔽凭证** - `buildRequestPreview` 将身份验证标头替换为 `Basic [REDACTED]`
- **CLI 参数可见性** - 通过 CLI 的 `--api-key` 在 `ps` 输出中可见；建议在生产环境中使用环境变量
- **云 LLM 注意事项** - 通过此服务器检索的数据可能会被云 AI 服务处理；请查看您组织的 数据处理政策
- **密钥轮换** - 在 WACM 下的个人资料 > WACM Connect 中定期重新生成 API 密钥
## 开发
```bash
pnpm install
pnpm dev # 使用 tsx 运行（自动重新加载）
pnpm build # 编译 TypeScript
pnpm test # 运行测试
pnpm lint # 校验代码
pnpm format # 格式化代码
pnpm check # 类型检查，不会发出
```
## 许可证
Apache-2.0
