wasabi-mcp

用于 Wasabi（兼容 S3 的热云存储）的 MCP 服务器。将 Wasabi Stats API 的存储桶利用率数据作为 MCP 工具暴露。

概述

• 无状态 HTTP 服务。不会持久化任何凭据——每个请求通过请求头提供自己的凭据，仅在该请求的生命周期内使用。

• 支持并发请求；每个请求的凭据隔离通过 Python contextvars 实现，而非全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

Related MCP server: mcp-server-s3

身份验证

Wasabi Stats API（stats.wasabisys.com）——一个独立于 S3 兼容对象存储 API 的、更简单的 API——使用单个静态请求头，无需登录/令牌交换：

Authorization: <AccessKey>:<SecretKey>

使用的密钥必须是 Wasabi Root 密钥，或附加了计费/统计策略（WasabiAccountStatsAccess 或 WasabiBucketStatsAccess）的子用户密钥——仅存储权限的密钥会被拒绝。这本身就已完全无状态，符合供应商的设计；MCP 调用之间不会缓存任何内容。

HEADER 授权参数说明

缺少任一请求头将返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-Wasabi-Access-Key and X-Wasabi-Secret-Key headers",
  "required_headers": ["X-Wasabi-Access-Key", "X-Wasabi-Secret-Key"],
  "optional_headers": []
}

环境变量

MCP 端点

• POST /mcp — MCP 协议（可流式 HTTP 传输）

• GET /health — 健康检查，返回 {"status": "ok"}（纯本地探测，不调用 Wasabi API）

工具列表

响应为供应商的原始 JSON（{"PageInfo": {...}, "Records": [...]}），紧凑序列化（无缩进，ensure_ascii=False），并限制为 20,000 个字符——如果 Records 列表会使响应超过该限制，则会被截断，并在负载中添加 truncated/truncated_field/original_count 标记。

错误处理

失败时，工具返回 JSON 错误封装（作为字符串，而非协议级错误），而不是抛出异常：

{"error": {"code": "upstream_error", "message": "...", "retryable": true}}

code 是固定词汇表之一：not_configured、unauthorized、not_found、invalid_argument、rate_limited、upstream_error。retryable 告知调用者重试是否值得。空结果集（请求范围内没有使用记录）作为正常的空结果返回，而非错误。

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Wasabi-Access-Key: <your-access-key>" \
  -H "X-Wasabi-Secret-Key: <your-secret-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "wasabi_get_bucket_utilizations",
      "arguments": {}
    }
  }'

已实测验证（2026-07-30）针对真实 Wasabi 账户：通过此运行中的服务器端到端调用 wasabi_get_bucket_utilizations 返回了真实数据——跨 270 页共 540 条真实存储桶利用率记录，包括 ap-southeast-2 区域中的真实存储桶名称（例如 "oraclegroup"、"centrewestib"），以及真实的存储/API 调用指标。

API 参考

• 公开，无需登录：

  • Overview: https://docs.wasabi.com/apidocs/wasabi-stats-api

  • Authentication: https://docs.wasabi.com/apidocs/authentication-with-wasabi-stats-api

  • This endpoint: https://docs.wasabi.com/apidocs/stats-api-get-v1standalone-bucket-utilizations

已知差距

• 范围恰好是 MSPbots 配置的 1 个端点，而非供应商的完整 API 表面——Wasabi Stats API 还提供账户级摘要端点（GET /v1/standalone/utilizations）以及按名称或编号的逐存储桶详细查询；这些不在本服务器范围内。Wasabi 兼容 S3 的对象存储 API（存储桶/对象 CRUD）是完全独立的 API，也不在范围内。

• MSPbots 为此集成存储的 region 字段未被本服务器使用——MSPbots 实际使用的那个端点（Stats API 存储桶利用率）具有固定的基础 URL（https://stats.wasabisys.com），无论给定存储桶位于哪个 Wasabi 区域；每条返回记录已包含自己的 Region 字段。region 仅对直接的 S3 兼容对象存储调用有意义，而本服务器不进行此类调用。

• from/to 日期范围默认值由供应商控制——如果省略，Wasabi 默认为“一个月前”到“今天”；本服务器不应用自己的默认值，仅在未提供时省略该参数。