@mgcrea/mcp-ovh

A Model Context Protocol server for the OVHcloud API, focused on Object Storage: buckets, objects, project users, S3 credentials and the storage policies that tie them together.

The server is read-only by default. Mutating tools are not merely refused when writes are off — they are never registered, so an agent cannot call them at all.

Features

• Curated tools over OVHcloud's /1.0 API with descriptions that spell out its traps (see Traps worth knowing).

• Read-only by default. OVH_ALLOW_WRITES=1 adds the write tools; the destructive ones then additionally require an explicit confirm: true on every call.

• All three OVH auth methods, picked automatically from whichever env vars are present: OAuth2 service account (recommended), application key + consumer key (SHA1-signed, with automatic clock-drift correction), or a static access token.

• Policy presets — including write-only, which OVH's own role shortcut does not offer.

• List results are summarized, and OVH's deprecated per-bucket objects[] array (which embeds every object in the bucket) is suppressed on both ends.

• X-Ovh-QueryID is surfaced on every error, because that is the first thing OVH support asks for.

• A secretFile parameter on every tool that mints or reveals a secret, so the secret can go to a 0600 file instead of the conversation (see Keeping secrets out of the transcript).

• An ovh_request escape hatch for the rest of the API (GET-only unless writes are enabled).

• Native fetch, no runtime dependencies beyond the MCP SDK and Zod.

Related MCP server: saveformedearai

Install

pnpm install
pnpm build

Configure

Pick one auth method.

(A) OAuth2 service account — recommended

1. Create an IAM service account at https://www.ovh.com/manager/#/iam/service-account.

2. Attach an IAM policy granting it your public cloud project (for object storage: publicCloudProject:apiovh:* on the project resource).

3. Copy the client id and secret into .env.

Tokens last an hour and are cached and refreshed ahead of expiry.

(B) Application key + consumer key

Create the triplet in one shot at https://eu.api.ovh.com/createToken/. The access rules you list there are fixed forever — a consumer key cannot be widened afterwards, so grant what you need up front:

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

Requests are SHA1-signed over secret+consumerKey+METHOD+URL+BODY+TIMESTAMP. A clock more than ~30s off OVH's fails every call with a misleading Invalid signature, so the server probes /auth/time once at startup and corrects for the delta.

(C) Static access token

Set OVH_ACCESS_TOKEN and it is sent as Authorization: Bearer.

cp .env.example .env

Run

pnpm start   # speaks JSON-RPC over stdio

Wire into Claude Code

Add to .mcp.json (project) or ~/.claude.json (global):

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

Inspect the tools

npx @modelcontextprotocol/inspector node dist/cli.js

Traps worth knowing

All are baked into the tool descriptions, but they explain the shape of this server:

1. OVH has no bucket policies — only user policies. One raw JSON document per project user, and that document is the entire access-control surface. Setting a policy replaces everything that user could previously do, across all buckets.

2. A policy cannot restrict the bucket's owner. OVH falls back to ACLs and the owner holds FULL_CONTROL: "if the user is the bucket owner and even if there is no explicit allow in the policy file, the user will be authorized." A restricted key must therefore belong to a new project user that did not create the bucket. ovh_provision_s3_user checks the bucket's ownerId and refuses when you point it at the owner.

3. The same fallback applies per object. Whoever uploads an object owns it and gets FULL_CONTROL on it through the object ACL. So merely omitting s3:GetObject does not stop an upload-only key from reading back everything it wrote — verified against the live API, where a bare allow-list policy happily served the key its own uploads while correctly denying every object someone else had uploaded. An explicit Deny is required, and it does beat the ACL. That is why the write-only preset ships a Deny statement rather than a bare allow-list.

Two smaller ones. s3:PutObject alone still permits blind overwrite of existing keys inside the allowed prefix — a "write-only" key is not an append-only key, which is a good reason to enable versioning on the bucket. And policy changes take up to ~30 seconds to propagate: a probe run five seconds after ovh_set_storage_policy still shows the old behaviour, which reads exactly like a policy that silently failed.

Tools

Every project-scoped tool takes an optional project, and every storage tool an optional region, overriding OVH_CLOUD_PROJECT / OVH_REGION per call. Tools marked W exist only when OVH_ALLOW_WRITES=1; those marked ⚠️ are destructive and additionally require confirm: true.

Start with ovh_whoami. It reports which auth method is live, which account you are, and the clock delta against OVH — which is what a 401 on the signature method is nearly always about.

ovh_presign_object is the only way bytes move: the server never proxies object content, it mints a time-limited presigned S3 URL instead. With writes off it signs GET only.

Policy presets

ovh_preview_policy, ovh_set_storage_policy and ovh_provision_s3_user share three presets, all scopable to a key prefix:

OVH's built-in roles (admin, deny, readOnly, readWrite, via ovh_grant_bucket_access) have no write-only equivalent — that is why the raw-policy path exists. The multipart pair is included deliberately: every S3 SDK auto-switches to multipart above ~8-16MB, and without abort/list a failed upload orphans parts the key holder cannot clean up and keeps paying for.

OVH validates policy actions against a fixed enum and rejects the whole document with a 400 if one is unknown — s3:GetObjectVersion and s3:DeleteObjectVersion exist in AWS but not there. The presets use only accepted actions, and a test pins that.

Handing out a write-only upload key

The motivating case: an app embeds an S3 key in a shipped binary, so the key must be able to upload and nothing else, while the read/write key stays with the developer.

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

That creates a new project user (never the bucket owner), applies the policy, and only then mints credentials — a key that exists before its policy is a key that briefly had whatever the default allows. The secret is returned once — add secretFile=/abs/path.json to have it written to a 0600 file instead of the conversation.

Verify against the real S3 API before handing it over — a policy that reads correctly can still be shadowed by ownership, and wait ~30s after setting it or you will be probing the previous policy:

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

The get-object line is the one that matters: it is the check that catches trap 3, and it passes only because of the preset's Deny.

Keeping secrets out of the transcript

Four tools return a live secret: ovh_create_s3_credentials and ovh_reveal_s3_secret (an S3 secret), ovh_provision_s3_user (an S3 access key and secret) and ovh_create_project_user (an OpenStack password). By default it comes back in the tool result, which means it lands in the assistant's transcript, and from there in whatever history the client keeps.

Pass secretFile to any of the four and the secret goes to that file instead. The result then carries only the non-secret fields (user id, username, access key, endpoint), the path, and a note that the secret is not in it.

ovh_provision_s3_user  bucket=dev-rgis-ar preset=write-only prefix=uploads/ \
                       secretFile=/Users/me/.secrets/ar-uploader.json confirm=true

{
  "access": "...",
  "secret": "...",
  "userId": 9001,
  "username": "user-...",
  "bucket": "dev-rgis-ar",
  "region": "uk",
  "endpoint": "https://s3.uk.io.cloud.ovh.net"
}

The S3 tools write access, secret and userId (provisioning adds the fields above); ovh_create_project_user writes username, password and userId.

• The path must be absolute and its directory must already exist — nothing is created for you but the file.

• The file is created exclusively with mode 0600: an existing file, or a symlink in its place, is refused and never overwritten.

• The path is checked before the OVH call, so a bad path does not mint a credential that then has nowhere to go. If the write still fails afterwards, the error names what was minted (access key, user id — never the secret) so you can revoke it.

• With OVH_SECRET_DIR set, the file must resolve inside that directory. Its parent is resolved through realpath, so a symlink inside the directory that points elsewhere is refused. Unset, any absolute path is accepted.

Without secretFile the tools behave exactly as before.

Develop

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

License

MIT