wasabi-mcp

MCP server for Wasabi (S3-compatible hot cloud storage). Exposes the Wasabi Stats API's bucket utilization data as an MCP tool.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own credentials via headers, used only for the lifetime of that single request.

• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.

• Entry points: POST /mcp (MCP protocol) and GET /health (health check).

• Default port: 8080 (configurable via MCP_HTTP_PORT).

Related MCP server: mcp-server-s3

Authentication

The Wasabi Stats API (stats.wasabisys.com) — a separate, simpler API from the S3-compatible object storage API — uses a single static header, with no login/token exchange:

Authorization: <AccessKey>:<SecretKey>

The keys used must be Wasabi Root keys, or sub-user keys with an attached billing/stats policy (WasabiAccountStatsAccess or WasabiBucketStatsAccess) — plain storage-only keys are rejected. This is already fully stateless by the vendor's own design; nothing is cached across MCP calls.

HEADER 授权参数说明

Missing either header returns 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": []
}

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)

• GET /health — health check, returns {"status": "ok"} (pure local probe, does not call the Wasabi API)

Tool List

Responses are the vendor's raw JSON ({"PageInfo": {...}, "Records": [...]}), serialized compactly (no indentation, ensure_ascii=False) and capped at 20,000 characters — if the Records list would push the response past that, it is truncated with truncated/truncated_field/original_count markers added to the payload.

Error Handling

On failure, tools return a JSON error envelope (as a string, not a protocol-level error) instead of raising:

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

code is one of a fixed vocabulary: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. retryable tells the caller whether retrying is worthwhile. Empty result sets (no usage records for the requested range) are returned as a normal empty result, not as an error.

测试示例

# 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": {}
    }
  }'

Live-verified (2026-07-30) against a real Wasabi account: wasabi_get_bucket_utilizations called end-to-end through this running server returned real data — 540 real bucket-utilization records across 270 pages, including real bucket names (e.g. "oraclegroup", "centrewestib") in the ap-southeast-2 region, with real storage/API-call metrics.

API Reference

• Public, no login required:

  • 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

Known Gaps

• Scope is exactly MSPbots' 1 configured endpoint, not the vendor's full API surface — the Wasabi Stats API also offers an account-level summary endpoint (GET /v1/standalone/utilizations) and per-bucket detail lookups by name or number; those are out of scope here. The Wasabi S3-compatible object storage API (bucket/object CRUD) is an entirely separate API and also out of scope.

• The region field MSPbots also stores for this integration is not used by this server — the one endpoint MSPbots actually uses (Stats API bucket utilizations) has a fixed base URL (https://stats.wasabisys.com) regardless of which Wasabi region a given bucket lives in; each returned record already includes its own Region field. region would only matter for direct S3-compatible object storage calls, which this server does not make.

• from/to date range defaults are vendor-controlled — if omitted, Wasabi defaults to "one month ago" through "today"; this server does not apply its own default and simply omits the parameter when not provided.