wasabi-mcp

Wasabi(S3 호환 핫 클라우드 스토리지)용 MCP 서버입니다. Wasabi Stats API의 bucket 사용량 데이터를 MCP 도구로 노출합니다.

개요

• 무상태(stateless) 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 key이거나, billing/stats 정책(WasabiAccountStatsAccess 또는 WasabiBucketStatsAccess)이 연결된 하위 사용자(sub-user) 키여야 합니다. 일반 스토리지 전용 키는 거부됩니다. 이는 공급업체 설계 자체가 이미 완전히 무상태이며, MCP 호출 간에 캐시되는 것이 없습니다.

헤더 인증 매개변수 설명

두 헤더 중 하나라도 없으면 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 프로토콜(streamable 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를 실행 중인 이 서버를 통해 엔드투엔드로 호출하여 실제 데이터를 반환했습니다 — ap-southeast-2 region의 실제 bucket 이름(예: "oraclegroup", "centrewestib")을 포함하여 270페이지에 걸친 540개의 실제 bucket 사용량 기록과 실제 스토리지/API 호출 메트릭입니다.

API 참조

• 공개, 로그인 불필요:

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

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

  • 이 엔드포인트: https://docs.wasabi.com/apidocs/stats-api-get-v1standalone-bucket-utilizations

알려진 한계

• 범위는 정확히 MSPbots가 구성한 1개의 엔드포인트이며, 공급업체의 전체 API 표면이 아닙니다 — Wasabi Stats API는 계정 수준 요약 엔드포인트(GET /v1/standalone/utilizations)와 이름 또는 번호로 조회하는 bucket별 상세 조회도 제공하지만, 이러한 항목은 여기서 범위 외입니다. Wasabi S3 호환 객체 스토리지 API(bucket/객체 CRUD)는 완전히 별개의 API이므로 역시 범위 외입니다.

• MSPbots가 이 통합에 대해 함께 저장하는 region 필드는 이 서버에서 사용되지 않습니다 — MSPbots가 실제로 사용하는 하나의 엔드포인트(Stats API bucket 사용량)는 특정 bucket이 어느 Wasabi region에 있든 기본 URL(https://stats.wasabisys.com)이 고정되어 있습니다. 반환되는 각 레코드에는 이미 자체 Region 필드가 포함되어 있습니다. region은 이 서버가 수행하지 않는 직접적인 S3 호환 객체 스토리지 호출에만 중요할 것입니다.

• from/to 날짜 범위 기본값은 공급업체가 제어합니다 — 생략하면 Wasabi는 "한 달 전"부터 "오늘"까지를 기본값으로 합니다. 이 서버는 자체 기본값을 적용하지 않으며, 제공되지 않으면 단순히 해당 매개변수를 생략합니다.