@mgcrea/mcp-ovh-api

Ein Model Context Protocol-Server für die OVHcloud-API, fokussiert auf Object Storage: Buckets, Objekte, Projektbenutzer, S3-Zugangsdaten und die Speicherrichtlinien, die sie zusammenhalten.

Der Server ist standardmäßig schreibgeschützt. Mutierende Werkzeuge werden nicht nur verweigert, wenn Schreibzugriff deaktiviert ist – sie werden nie registriert, sodass ein Agent sie überhaupt nicht aufrufen kann.

Funktionen

• Kuratierte Werkzeuge über die /1.0-API von OVHcloud mit Beschreibungen, die deren Fallstricke ausführen (siehe Wissenswerte Fallstricke).

• Standardmäßig schreibgeschützt. OVH_ALLOW_WRITES=1 fügt die Schreibwerkzeuge hinzu; die destruktiven erfordern dann zusätzlich bei jedem Aufruf ein explizites confirm: true.

• Alle drei OVH-Authentifizierungsmethoden, automatisch ausgewählt anhand der vorhandenen Umgebungsvariablen: OAuth2-Dienstkonto (empfohlen), Anwendungsschlüssel + Consumer-Key (SHA1-signiert, mit automatischer Korrektur der Uhrzeitabweichung) oder ein statisches Zugriffstoken.

• Richtlinienvoreinstellungen – einschließlich write-only, das OVHs eigene Rollenabkürzung nicht bietet.

• Listenergebnisse werden zusammengefasst, und OVHs veraltetes, pro-Bucket-objects[]-Array (das jedes Objekt im Bucket einbettet) wird auf beiden Seiten unterdrückt.

• X-Ovh-QueryID wird bei jedem Fehler angezeigt, weil das das Erste ist, wonach der OVH-Support fragt.

• Ein ovh_request-Notausgang für den Rest der API (nur GET, sofern Schreibzugriff nicht aktiviert ist).

• Natives fetch, keine Laufzeitabhängigkeiten außer dem MCP-SDK und Zod.

Installieren

pnpm install
pnpm build

Konfigurieren

Wählen Sie eine Authentifizierungsmethode.

(A) OAuth2-Dienstkonto – empfohlen

1. Erstellen Sie ein IAM-Dienstkonto unter https://www.ovh.com/manager/#/iam/service-account.

2. Weisen Sie ihm eine IAM-Richtlinie zu, die Ihrem Public-Cloud-Projekt Zugriff gewährt (für Object Storage: publicCloudProject:apiovh:* auf die Projektressource).

3. Kopieren Sie Client-ID und Secret in .env.

Tokens gelten eine Stunde und werden vor Ablauf zwischengespeichert und erneuert.

(B) Anwendungsschlüssel + Consumer-Key

Erstellen Sie das Trio in einem Schritt unter https://eu.api.ovh.com/createToken/. Die dort aufgeführten Zugriffsregeln sind für immer festgelegt – ein Consumer-Key kann später nicht erweitert werden. Gewähren Sie also von vornherein, was Sie benötigen:

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

Anfragen werden mit SHA1 über secret+consumerKey+METHOD+URL+BODY+TIMESTAMP signiert. Eine Uhr, die mehr als ~30s von OVH abweicht, lässt jeden Aufruf mit einem irreführenden Invalid signature fehlschlagen. Der Server prüft daher beim Start einmal /auth/time und korrigiert die Abweichung.

(C) Statisches Zugriffstoken

Setzen Sie OVH_ACCESS_TOKEN, und es wird als Authorization: Bearer gesendet.

cp .env.example .env

Ausführen

pnpm start   # speaks JSON-RPC over stdio

In Claude Code einbinden

Fügen Sie zu .mcp.json (Projekt) oder ~/.claude.json (global) hinzu:

{
  "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"
      }
    }
  }
}

Werkzeuge anzeigen

npx @modelcontextprotocol/inspector node dist/cli.js

Wissenswerte Fallstricke

Alle sind in die Werkzeugbeschreibungen eingearbeitet, aber sie erklären die Form dieses Servers:

1. *OVH hat keine Bucket-Richtlinien – nur Benutzerrichtlinien.* Ein rohes JSON-Dokument pro Projektbenutzer, und dieses Dokument ist die gesamte Zugriffskontrollfläche. Das Setzen einer Richtlinie ersetzt alles, was dieser Benutzer zuvor konnte, über alle Buckets hinweg.

2. Eine Richtlinie kann den Besitzer des Buckets nicht einschränken. OVH fällt auf ACLs zurück, und der Besitzer hat FULL_CONTROL: „Wenn der Benutzer der Bucket-Besitzer ist und selbst wenn es keine explizite Erlaubnis in der Richtliniendatei gibt, wird der Benutzer autorisiert." Ein eingeschränkter Schlüssel muss daher zu einem neuen Projektbenutzer gehören, der den Bucket nicht erstellt hat. ovh_provision_s3_user prüft die ownerId des Buckets und verweigert, wenn Sie auf den Besitzer zeigen.

3. Derselbe Rückfall gilt pro Objekt. Wer ein Objekt hochlädt, besitzt es und erhält FULL_CONTROL darauf über die Objekt-ACL. Das bloße Weglassen von s3:GetObject verhindert also nicht, dass ein Nur-Upload-Schlüssel alles zurücklesen kann, was er geschrieben hat – verifiziert gegen die Live-API, wo eine bloße Allow-List-Richtlinie dem Schlüssel problemlos seine eigenen Uploads auslieferte, während sie korrekt jedes Objekt verweigerte, das jemand anderes hochgeladen hatte. Ein explizites Deny ist erforderlich, und es schlägt die ACL. Deshalb liefert die write-only-Voreinstellung eine Deny-Anweisung statt einer bloßen Allow-List.

Zwei kleinere. s3:PutObject allein erlaubt weiterhin blindes Überschreiben vorhandener Schlüssel innerhalb des erlaubten Präfixes – ein „write-only"-Schlüssel ist kein Append-only-Schlüssel, was ein guter Grund ist, Versionierung auf dem Bucket zu aktivieren. Und Richtlinienänderungen brauchen bis zu ~30 Sekunden, um sich auszubreiten: Ein Testlauf fünf Sekunden nach ovh_set_storage_policy zeigt noch das alte Verhalten, was sich genau wie eine still fehlgeschlagene Richtlinie liest.

Werkzeuge

Jedes projektbezogene Werkzeug akzeptiert ein optionales project, und jedes Speicherwerkzeug eine optionale region, die OVH_CLOUD_PROJECT / OVH_REGION pro Aufruf überschreiben. Mit W markierte Werkzeuge existieren nur, wenn OVH_ALLOW_WRITES=1; mit ⚠️ markierte sind destruktiv und erfordern zusätzlich confirm: true.

Beginnen Sie mit ovh_whoami. Es meldet, welche Authentifizierungsmethode aktiv ist, welches Konto Sie sind und die Uhrzeitabweichung gegenüber OVH – worum es bei einem 401 bei der Signaturmethode fast immer geht.

ovh_presign_object ist der einzige Weg, auf den Bytes bewegt werden: Der Server proxyt nie Objektinhalte, sondern erstellt stattdessen eine zeitlich begrenzte vorsignierte S3-URL. Bei deaktiviertem Schreibzugriff signiert er nur GET.

Richtlinienvoreinstellungen

ovh_preview_policy, ovh_set_storage_policy und ovh_provision_s3_user teilen drei Voreinstellungen, alle auf einen Schlüsselpräfix eingrenzbar:

OVHs eingebaute Rollen (admin, deny, readOnly, readWrite, über ovh_grant_bucket_access) haben kein write-only-Äquivalent – deshalb existiert der Rohrichtlinien-Pfad. Das Multipart-Paar ist absichtlich enthalten: Jedes S3-SDK wechselt oberhalb von ~8-16MB automatisch zu Multipart, und ohne abort/list verwaist ein fehlgeschlagener Upload Teile, die der Schlüsselinhaber nicht aufräumen kann und weiterhin bezahlt.

OVH validiert Richtlinienaktionen gegen eine feste Enumeration und lehnt das gesamte Dokument mit einem 400 ab, wenn eine unbekannt ist – s3:GetObjectVersion und s3:DeleteObjectVersion existieren in AWS, aber nicht dort. Die Voreinstellungen verwenden nur akzeptierte Aktionen, und ein Test fixiert das.

Ausgabe eines Write-only-Upload-Schlüssels

Der motivierende Fall: Eine App bettet einen S3-Schlüssel in ein ausgeliefertes Binärprogramm ein, sodass der Schlüssel nur hochladen und sonst nichts können darf, während der Lese-/Schreibschlüssel beim Entwickler bleibt.

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

Das erstellt einen neuen Projektbenutzer (niemals den Bucket-Besitzer), wendet die Richtlinie an und erstellt erst dann Zugangsdaten – ein Schlüssel, der vor seiner Richtlinie existiert, ist ein Schlüssel, der kurzzeitig hatte, was die Standardeinstellung erlaubt. Das Secret wird einmal zurückgegeben.

Verifizieren Sie gegen die echte S3-API, bevor Sie ihn übergeben – eine Richtlinie, die korrekt liest, kann immer noch durch Eigentum überschattet werden, und warten Sie ~30s nach dem Setzen, sonst testen Sie die vorherige Richtlinie:

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

Die get-object-Zeile ist die, die zählt: Sie ist die Prüfung, die Fallstrick 3 abfängt, und sie besteht nur wegen des Deny der Voreinstellung.

Entwickeln

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

Lizenz

MIT