@mgcrea/mcp-ovh-api

OVHcloud API용 Model Context Protocol 서버로, Object Storage에 초점을 맞춥니다: 버킷, 객체, 프로젝트 사용자, S3 자격 증명, 그리고 이들을 묶는 스토리지 정책을 다룹니다.

이 서버는 기본적으로 읽기 전용입니다. 쓰기 작업이 꺼져 있을 때 변경 도구는 단순히 거부되는 것이 아니라 아예 등록되지 않으므로, 에이전트가 해당 도구를 호출할 수 없습니다.

기능

• OVHcloud의 /1.0 API에 대한 선별된 도구와, 그 함정을 설명하는 설명( 알아야 할 함정 참조).

• 기본적으로 읽기 전용. OVH_ALLOW_WRITES=1이면 쓰기 도구가 추가되며, 파괴적인 도구는 매 호출 시 명시적인 confirm: true를 추가로 요구합니다.

• OVH의 세 가지 인증 방법 모두 지원하며, 존재하는 환경 변수에 따라 자동으로 선택됩니다: OAuth2 서비스 계정(권장), 애플리케이션 키 + 소비자 키(SHA1 서명, 자동 시계 오프셋 보정 포함), 또는 정적 액세스 토큰.

• 정책 프리셋 — OVH 자체 역할 단축키가 제공하지 않는 write-only 포함.

• 목록 결과는 요약되며, OVH의 폐기된 버킷별 objects[] 배열(버킷의 모든 객체를 포함)은 양쪽에서 억제됩니다.

• 모든 오류에 X-Ovh-QueryID가 표시됩니다. OVH 지원팀이 가장 먼저 묻는 것이기 때문입니다.

• 나머지 API를 위한 ovh_request 탈출구(쓰기가 활성화되지 않으면 GET 전용).

• 네이티브 fetch, MCP SDK와 Zod 외에 런타임 의존성 없음.

설치

pnpm install
pnpm build

구성

인증 방법 하나를 선택하세요.

(A) OAuth2 서비스 계정 — 권장

1. https://www.ovh.com/manager/#/iam/service-account에서 IAM 서비스 계정을 생성합니다.

2. 공용 클라우드 프로젝트에 대한 IAM 정책을 연결합니다(객체 스토리지의 경우: 프로젝트 리소스에 publicCloudProject:apiovh:*).

3. 클라이언트 ID와 시크릿을 .env에 복사합니다.

토큰은 1시간 동안 유효하며, 만료 전에 캐시되고 갱신됩니다.

(B) 애플리케이션 키 + 소비자 키

https://eu.api.ovh.com/createToken/에서 한 번에 세 개를 생성하세요. 여기에 나열한 액세스 규칙은 영구적으로 고정됩니다 — 소비자 키는 이후에 확장할 수 없으므로, 처음에 필요한 것을 모두 부여하세요:

GET    /cloud/project/*
POST   /cloud/project/*
PUT    /cloud/project/*
DELETE /cloud/project/*
GET    /me

요청은 secret+consumerKey+METHOD+URL+BODY+TIMESTAMP에 대해 SHA1 서명됩니다. OVH와 시계가 ~30초 이상 차이 나면 모든 호출이 오해를 부르는 Invalid signature로 실패하므로, 서버는 시작 시 /auth/time을 한 번 프로브하여 차이를 보정합니다.

(C) 정적 액세스 토큰

OVH_ACCESS_TOKEN을 설정하면 Authorization: Bearer로 전송됩니다.

cp .env.example .env

실행

pnpm start   # speaks JSON-RPC over stdio

Claude Code에 연결

.mcp.json(프로젝트) 또는 ~/.claude.json(전역)에 추가:

{
  "mcpServers": {
    "ovh": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-ovh-api/dist/cli.js"],
      "env": {
        "OVH_CLIENT_ID": "...",
        "OVH_CLIENT_SECRET": "...",
        "OVH_CLOUD_PROJECT": "abcdef0123456789abcdef0123456789",
        "OVH_REGION": "UK"
      }
    }
  }
}

도구 검사

npx @modelcontextprotocol/inspector node dist/cli.js

알아야 할 함정

모두 도구 설명에 포함되어 있지만, 이 서버의 형태를 설명합니다:

1. OVH에는 버킷 정책이 없습니다 — 사용자 정책만 있습니다. 프로젝트 사용자당 원시 JSON 문서 하나가 있으며, 그 문서가 전체 액세스 제어 표면입니다. 정책을 설정하면 해당 사용자가 이전에 할 수 있었던 모든 것이 모든 버킷에 걸쳐 대체됩니다.

2. 정책은 버킷 소유자를 제한할 수 없습니다. OVH는 ACL로 폴백하며 소유자는 FULL_CONTROL을 보유합니다: "사용자가 버킷 소유자이고 정책 파일에 명시적 허용이 없더라도 사용자는 권한이 부여됩니다." 따라서 제한된 키는 버킷을 생성하지 않은 새 프로젝트 사용자에게 속해야 합니다. ovh_provision_s3_user는 버킷의 ownerId를 확인하고 소유자를 가리키면 거부합니다.

3. 동일한 폴백이 객체별로 적용됩니다. 객체를 업로드하는 사람은 그 객체를 소유하며 객체 ACL을 통해 FULL_CONTROL을 얻습니다. 따라서 s3:GetObject를 단순히 생략하는 것은 업로드 전용 키가 자신이 쓴 모든 것을 다시 읽는 것을 막지 못합니다 — 라이브 API에서 검증되었으며, 순수 허용 목록 정책이 자신의 업로드를 키에 제공하면서 다른 사람이 업로드한 모든 객체는 올바르게 거부했습니다. 명시적 Deny 가 필요하며, ACL을 이깁니다. 이것이 write-only 프리셋이 순수 허용 목록 대신 Deny 문을 제공하는 이유입니다.

두 가지 더 작은 것. s3:PutObject만으로도 허용된 접두사 내의 기존 키를 맹목적으로 덮어쓰는 것이 가능합니다 — "write-only" 키는 append-only 키가 아니므로, 버킷에 버전 관리를 활성화하는 것이 좋은 이유입니다. 그리고 정책 변경은 전파되는 데 최대 ~30초가 걸립니다: ovh_set_storage_policy 후 5초 후에 실행한 프로브는 여전히 이전 동작을 보여주며, 이는 정책이 조용히 실패한 것처럼 읽힙니다.

도구

모든 프로젝트 범위 도구는 선택적 project를, 모든 스토리지 도구는 선택적 region을 받아 호출별로 OVH_CLOUD_PROJECT / OVH_REGION을 재정의합니다. W로 표시된 도구는 OVH_ALLOW_WRITES=1일 때만 존재하며, ⚠️로 표시된 도구는 파괴적이며 추가로 confirm: true가 필요합니다.

ovh_whoami부터 시작하세요. 어떤 인증 방법이 활성화되어 있는지, 어떤 계정인지, OVH에 대한 시계 차이를 보고합니다 — 서명 방법에서 401이 발생하는 경우 거의 항상 이 때문입니다.

ovh_presign_object는 바이트가 이동하는 유일한 방법입니다: 서버는 객체 콘텐츠를 프록시하지 않고 시간 제한이 있는 사전 서명된 S3 URL을 발급합니다. 쓰기가 꺼져 있으면 GET만 서명합니다.

정책 프리셋

ovh_preview_policy, ovh_set_storage_policy 및 ovh_provision_s3_user는 세 가지 프리셋을 공유하며, 모두 키 접두사로 범위를 지정할 수 있습니다:

OVH의 내장 역할(admin, deny, readOnly, readWrite, ovh_grant_bucket_access를 통해)에는 write-only에 해당하는 것이 없습니다 — 이것이 원시 정책 경로가 존재하는 이유입니다. 멀티파트 쌍은 의도적으로 포함되었습니다: 모든 S3 SDK는 ~8-16MB 이상에서 자동으로 멀티파트로 전환하며, abort/list가 없으면 실패한 업로드가 키 보유자가 정리할 수 없는 부분을 남겨 계속 비용을 지불하게 됩니다.

OVH는 정책 작업을 고정된 열거형에 대해 검증하며, 알 수 없는 작업이 있으면 전체 문서를 400으로 거부합니다 — s3:GetObjectVersion 및 s3:DeleteObjectVersion은 AWS에는 있지만 여기에는 없습니다. 프리셋은 허용된 작업만 사용하며, 테스트가 이를 고정합니다.

write-only 업로드 키 발급

동기: 앱이 배포된 바이너리에 S3 키를 포함하므로, 키는 업로드만 가능하고 다른 것은 할 수 없어야 하며, 읽기/쓰기 키는 개발자에게 남아 있어야 합니다.

ovh_get_bucket           bucket=dev-rgis-ar          → note ownerId
ovh_preview_policy       bucket=dev-rgis-ar preset=write-only prefix=uploads/
ovh_provision_s3_user    bucket=dev-rgis-ar preset=write-only prefix=uploads/ \
                         description=ar-app-uploader confirm=true

이것은 새 프로젝트 사용자(절대 버킷 소유자 아님)를 생성하고, 정책을 적용한 다음에만 자격 증명을 발급합니다 — 정책보다 먼저 존재하는 키는 기본값이 허용하는 것을 잠시 가진 키입니다. 시크릿은 한 번만 반환됩니다.

실제 S3 API에 대해 검증한 후 전달하세요 — 올바르게 읽히는 정책도 소유권에 의해 가려질 수 있으며, 설정 후 ~30초를 기다리지 않으면 이전 정책을 프로브하게 됩니다:

export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
# An array, not a string: zsh does not word-split an unquoted $var, so the
# `S3='aws ...'` form you would write in bash silently becomes "command not found".
S3=(aws --endpoint-url https://s3.uk.io.cloud.ovh.net --region uk s3api)
"${S3[@]}" put-object      --bucket dev-rgis-ar --key uploads/probe.txt --body /dev/null   # 200
"${S3[@]}" get-object      --bucket dev-rgis-ar --key uploads/probe.txt /dev/null          # 403
"${S3[@]}" list-objects-v2 --bucket dev-rgis-ar                                            # 403
"${S3[@]}" delete-object   --bucket dev-rgis-ar --key uploads/probe.txt                    # 403
"${S3[@]}" put-object      --bucket dev-rgis-ar --key elsewhere/probe.txt --body /dev/null # 403

get-object 줄이 중요한 것입니다: 함정 3을 잡는 검사이며, 프리셋의 Deny 덕분에 통과합니다.

개발

pnpm dev            # tsdown --watch
pnpm test           # vitest
pnpm typecheck
pnpm lint
pnpm format

라이선스

MIT