@mgcrea/mcp-ovh-api

Un servidor Model Context Protocol para la API de OVHcloud, centrado en Object Storage: buckets, objetos, usuarios de proyecto, credenciales S3 y las políticas de almacenamiento que los unen.

El servidor es de solo lectura por defecto. Las herramientas de mutación no solo se rechazan cuando los escritos están desactivados — nunca se registran, por lo que un agente no puede llamarlas en absoluto.

Características

• Herramientas seleccionadas sobre la API /1.0 de OVHcloud con descripciones que explican sus trampas (ver Trampas que conviene conocer).

• Solo lectura por defecto. OVH_ALLOW_WRITES=1 añade las herramientas de escritura; las destructivas requieren además un confirm: true explícito en cada llamada.

• Los tres métodos de autenticación de OVH, elegidos automáticamente según las variables de entorno presentes: cuenta de servicio OAuth2 (recomendada), clave de aplicación + clave de consumidor (firmada con SHA1, con corrección automática de desviación de reloj), o un token de acceso estático.

• Presets de políticas — incluyendo write-only, que el atajo de roles de OVH no ofrece.

• Los resultados de listas se resumen, y el array objects[] obsoleto por bucket de OVH (que incrusta todos los objetos del bucket) se suprime en ambos extremos.

• X-Ovh-QueryID se muestra en cada error, porque es lo primero que pide el soporte de OVH.

• Una vía de escape ovh_request para el resto de la API (solo GET a menos que los escritos estén habilitados).

• fetch nativo, sin dependencias de ejecución más allá del SDK de MCP y Zod.

Instalar

pnpm install
pnpm build

Configurar

Elige un método de autenticación.

(A) Cuenta de servicio OAuth2 — recomendada

1. Crea una cuenta de servicio IAM en https://www.ovh.com/manager/#/iam/service-account.

2. Adjunta una política IAM que le conceda tu proyecto de cloud público (para object storage: publicCloudProject:apiovh:* en el recurso del proyecto).

3. Copia el client id y el secreto en .env.

Los tokens duran una hora y se almacenan en caché y se renuevan antes de que expiren.

(B) Clave de aplicación + clave de consumidor

Crea el trío de una sola vez en https://eu.api.ovh.com/createToken/. Las reglas de acceso que enumeres allí quedan fijas para siempre — una clave de consumidor no se puede ampliar después, así que concede lo que necesites desde el principio:

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

Las solicitudes se firman con SHA1 sobre secret+consumerKey+METHOD+URL+BODY+TIMESTAMP. Un reloj más de ~30s desviado del de OVH hace fallar todas las llamadas con un engañoso Invalid signature, por lo que el servidor sondea /auth/time una vez al inicio y corrige la diferencia.

(C) Token de acceso estático

Establece OVH_ACCESS_TOKEN y se envía como Authorization: Bearer.

cp .env.example .env

Ejecutar

pnpm start   # speaks JSON-RPC over stdio

Conectar con Claude Code

Añade a .mcp.json (proyecto) o ~/.claude.json (global):

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

Inspeccionar las herramientas

npx @modelcontextprotocol/inspector node dist/cli.js

Trampas que conviene conocer

Todas están integradas en las descripciones de las herramientas, pero explican la forma de este servidor:

1. OVH no tiene políticas de bucket — solo políticas de usuario. Un único documento JSON en bruto por usuario de proyecto, y ese documento es toda la superficie de control de acceso. Establecer una política reemplaza todo lo que ese usuario podía hacer antes, en todos los buckets.

2. Una política no puede restringir al propietario del bucket. OVH recurre a las ACL y el propietario tiene FULL_CONTROL: "si el usuario es el propietario del bucket y aunque no haya un allow explícito en el archivo de política, el usuario estará autorizado". Por lo tanto, una clave restringida debe pertenecer a un nuevo usuario de proyecto que no haya creado el bucket. ovh_provision_s3_user comprueba el ownerId del bucket y se niega cuando lo apuntas al propietario.

3. La misma regla se aplica por objeto. Quien sube un objeto lo posee y obtiene FULL_CONTROL sobre él a través de la ACL del objeto. Así que simplemente omitir s3:GetObject no impide que una clave de solo subida pueda leer todo lo que escribió — verificado contra la API en vivo, donde una política de lista de allows desnuda servía a la clave sus propias subidas mientras denegaba correctamente todos los objetos que otro había subido. Un Deny explícito es necesario, y sí supera a la ACL. Por eso el preset write-only incluye una declaración Deny en lugar de una lista de allows desnuda.

Dos más pequeñas. s3:PutObject solo aún permite la sobrescritura ciega de claves existentes dentro del prefijo permitido — una clave "write-only" no es una clave de solo añadir, lo cual es una buena razón para activar el versionado en el bucket. Y los cambios de política tardan hasta ~30 segundos en propagarse: una prueba ejecutada cinco segundos después de ovh_set_storage_policy todavía muestra el comportamiento anterior, lo que se lee exactamente como una política que falló en silencio.

Herramientas

Cada herramienta con ámbito de proyecto acepta un project opcional, y cada herramienta de almacenamiento un region opcional, sobrescribiendo OVH_CLOUD_PROJECT / OVH_REGION por llamada. Las herramientas marcadas con W existen solo cuando OVH_ALLOW_WRITES=1; las marcadas con ⚠️ son destructivas y además requieren confirm: true.

Empieza con ovh_whoami. Informa de qué método de autenticación está activo, qué cuenta eres y la diferencia de reloj con OVH — que es de lo que casi siempre trata un 401 en el método de firma.

ovh_presign_object es la única forma de mover bytes: el servidor nunca hace de proxy del contenido de los objetos, sino que genera una URL S3 presignada con límite de tiempo. Con los escritos desactivados firma solo GET.

Presets de políticas

ovh_preview_policy, ovh_set_storage_policy y ovh_provision_s3_user comparten tres presets, todos acotables a un prefijo de clave:

Los roles integrados de OVH (admin, deny, readOnly, readWrite, vía ovh_grant_bucket_access) no tienen equivalente de solo escritura — por eso existe la ruta de política en bruto. El par de multipart se incluye deliberadamente: todo SDK de S3 cambia automáticamente a multipart por encima de ~8-16MB, y sin abort/list una subida fallida deja partes huérfanas que el titular de la clave no puede limpiar y por las que sigue pagando.

OVH valida las acciones de las políticas contra un enum fijo y rechaza el documento completo con un 400 si una es desconocida — s3:GetObjectVersion y s3:DeleteObjectVersion existen en AWS pero no allí. Los presets usan solo acciones aceptadas, y una prueba lo fija.

Entregar una clave de subida de solo escritura

El caso motivador: una aplicación incrusta una clave S3 en un binario distribuido, por lo que la clave debe poder subir y nada más, mientras que la clave de lectura/escritura queda en manos del desarrollador.

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

Eso crea un nuevo usuario de proyecto (nunca el propietario del bucket), aplica la política, y solo entonces genera credenciales — una clave que existe antes de su política es una clave que brevemente tuvo lo que el valor por defecto permita. El secreto se devuelve una sola vez.

Verifica contra la API S3 real antes de entregarla — una política que se lee correctamente puede seguir siendo ensombrecida por la propiedad, y espera ~30s después de establecerla o estarás probando la política anterior:

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

La línea get-object es la que importa: es la comprobación que detecta la trampa 3, y pasa solo gracias al Deny del preset.

Desarrollar

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

Licencia

MIT