Cloudinary

oficial

Interactuar con la plataforma de gestión de medios de

GitHub
10

¿Qué puedes hacer con Cloudinary MCP?

  • Subir y gestionar archivos multimedia — Sube imágenes, videos y archivos sin procesar, y luego organízalos con carpetas, etiquetas y relaciones entre recursos.
  • Buscar y transformar recursos — Busca recursos con filtros avanzados y aplica operaciones y transformaciones.
  • Generar imágenes con IA — Crea imágenes nuevas a partir de indicaciones de texto o imágenes de referencia y guárdalas en tu cuenta.
  • Analizar contenido multimedia — Ejecuta el etiquetado con IA, la moderación, la generación de subtítulos, la detección de objetos y el análisis de marcas de agua o de calidad en los recursos.
  • Configurar los ajustes del entorno — Crea transformaciones con nombre, ajustes preestablecidos de carga, perfiles de streaming y activadores de webhook.
  • Gestionar metadatos estructurados — Crea campos de metadatos, establece reglas de validación y gestiona los valores de origen de datos para los campos de tipo lista.

Servidor MCP alojado

npx add-mcp 'https://asset-management.mcp.cloudinary.com/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Servidores MCP de Cloudinary

El Protocolo de Contexto de Modelo (MCP) es un protocolo nuevo y estandarizado para gestionar el contexto entre los modelos de lenguaje grandes (LLM) y los sistemas externos. Este repositorio proporciona servidores MCP completos para la plataforma de gestión de medios de Cloudinary, que te permiten usar lenguaje natural para cargar, generar, transformar, analizar y organizar tus recursos multimedia directamente desde aplicaciones de IA como Cursor y Claude.

Con estos servidores MCP, puedes gestionar sin problemas todo tu flujo de trabajo multimedia mediante IA conversacional: desde cargar, generar y transformar imágenes y vídeos hasta configurar canalizaciones de procesamiento automatizadas, analizar contenido con herramientas basadas en IA y organizar recursos con metadatos estructurados. Tanto si estás creando aplicaciones con abundante contenido multimedia, gestionando grandes bibliotecas de recursos o automatizando flujos de trabajo de contenido, estos servidores proporcionan acceso directo a todo el conjunto de capacidades de optimización y gestión de medios de Cloudinary.

Los siguientes servidores MCP están disponibles para Cloudinary:

Nombre del servidorDescripciónServidor MCP remoto
Gestión de recursosCarga, gestiona, busca y transforma tus recursos multimedia, y genera imágenes nuevas con IA a partir de indicaciones de texto o imágenes de referenciaasset-management
Configuración del entornoConfigura y gestiona los ajustes de tu entorno de Cloudinary, los ajustes preestablecidos de carga y las transformacionesenvironment-config
Metadatos estructuradosCrea, gestiona y consulta campos de metadatos estructurados para mejorar la organización y la capacidad de búsqueda de los recursosstructured-metadata
AnálisisAprovecha las capacidades de análisis de contenido, moderación y etiquetado automático basadas en IA para tus recursos multimediaanalysis
MediaFlowsCrea y gestiona automatizaciones de flujos de trabajo de bajo código para imágenes y vídeos con asistencia basada en IAmediaflows

Tabla de contenido

Documentación

Para consultar guías detalladas, tutoriales y documentación completa sobre el uso de los servidores MCP de Cloudinary:

Instalación

Servidores MCP remotos (recomendado)

Los servidores MCP remotos están alojados por Cloudinary y listos para usarse de inmediato. No es necesario instalarlos localmente.

Servidores MCP locales

Los servidores MCP locales se ejecutan en tu equipo mediante paquetes npm. Elige esta opción si necesitas más control o personalización.

Nota: Después de la instalación, tendrás que configurar las variables de entorno (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET) con tus credenciales reales.

Imágenes de Docker

Las imágenes oficiales de Docker para los servidores MCP de Cloudinary están disponibles en Docker Hub y ofrecen una opción de implementación en contenedores para ejecutar servidores MCP localmente o en entornos de nube.

Disponibles en Docker Hub: Imágenes de Docker de Cloudinary MCP

Las imágenes de Docker ofrecen varias ventajas:

  • Entornos aislados - Ejecuta servidores MCP en contenedores sin afectar las dependencias de tu sistema
  • Implementación sencilla - Configuración rápida con requisitos mínimos de configuración
  • Entorno de ejecución uniforme - Garantiza el mismo entorno en distintas máquinas y plataformas
  • Escalabilidad - Implementa fácilmente varias instancias o intégralas en sistemas de orquestación de contenedores

Para usar imágenes de Docker, asegúrate de tener Docker instalado en tu sistema y pasa tus credenciales de Cloudinary como variables de entorno al ejecutar los contenedores. Consulta la documentación de cada imagen de Docker en Docker Hub para obtener instrucciones de uso específicas.

Ejemplos de configuración

Configuración de servidores MCP remotos

Los servidores remotos están alojados por Cloudinary y se accede a ellos mediante una URL:

{
  "mcpServers": {
    "cloudinary-asset-mgmt-remote": {
      "url": "https://asset-management.mcp.cloudinary.com/mcp"
    },
    "cloudinary-env-config-remote": {
      "url": "https://environment-config.mcp.cloudinary.com/mcp"
    },
    "cloudinary-smd-remote": {
      "url": "https://structured-metadata.mcp.cloudinary.com/mcp"
    },
    "cloudinary-analysis-remote": {
      "url": "https://analysis.mcp.cloudinary.com/mcp"
    },
    "mediaflows": {
      "url": "https://mediaflows.mcp.cloudinary.com/v2/mcp"
    }
  }
}

Transporte: Los servidores remotos admiten dos endpoints: /mcp (Streamable HTTP, recomendado y sin estado) y /sse (SSE, obsoleto, se mantiene por compatibilidad con versiones anteriores). El endpoint /sse también acepta solicitudes POST como alias de /mcp, por lo que funcionarán los clientes que envíen Streamable HTTP a /sse. Usa /mcp en las configuraciones nuevas.

Servidores MCP remotos con autenticación

Los servidores MCP remotos alojados por Cloudinary usan OAuth2 de forma predeterminada para la autenticación. También puedes autenticarte mediante claves de API en los encabezados:

Uso de CLOUDINARY_URL (la opción más sencilla)

{
  "mcpServers": {
    "cloudinary-asset-mgmt-remote": {
      "url": "https://asset-management.mcp.cloudinary.com/mcp",
      "headers": {
        "cloudinary-url": "cloudinary://api_key:api_secret@cloud_name"
      }
    }
  }
}

Uso de encabezados individuales

{
  "mcpServers": {
    "cloudinary-env-config-remote": {
      "url": "https://environment-config.mcp.cloudinary.com/mcp",
      "headers": {
        "cloudinary-cloud-name": "your_cloud_name",
        "cloudinary-api-key": "your_api_key",
        "cloudinary-api-secret": "your_api_secret"
      }
    }
  }
}

Con configuración personalizada

{
  "mcpServers": {
    "cloudinary-smd-remote": {
      "url": "https://structured-metadata.mcp.cloudinary.com/mcp",
      "headers": {
        "cloudinary-url": "cloudinary://api_key:api_secret@cloud_name",
        "cloudinary-region": "api-eu",
        "cloudinary-tools": "list-metadata-fields,get-metadata-field,create-metadata-field"
      }
    }
  }
}

Con encabezados de depuración

Para mostrar los encabezados de límite de velocidad de la API y los ID de solicitud en los resultados de las herramientas, habilita la inclusión de encabezados:

{
  "mcpServers": {
    "cloudinary-asset-mgmt-remote": {
      "url": "https://asset-management.mcp.cloudinary.com/mcp",
      "headers": {
        "cloudinary-url": "cloudinary://api_key:api_secret@cloud_name",
        "cloudinary-embed-headers": "true"
      }
    }
  }
}

Cada resultado de herramienta incluirá un campo _headers con información sobre los límites de velocidad y el seguimiento de solicitudes:

{
  "_headers": {
    "x-featureratelimit-limit": "10000",
    "x-featureratelimit-remaining": "9998",
    "x-featureratelimit-reset": "Thu, 13 Feb 2026 00:00:00 GMT",
    "x-request-id": "bfeaccc60050594832508590a358a1a4"
  }
}

Configuración de servidores MCP locales

Los servidores locales se ejecutan en tu equipo mediante paquetes npm:

Opción 1: Uso de la variable de entorno CLOUDINARY_URL (recomendado)

{
  "mcpServers": {
    "cloudinary-asset-mgmt": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/asset-management-mcp", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_URL": "cloudinary://api_key:api_secret@cloud_name"
      }
    },
    "cloudinary-env-config": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/environment-config-mcp", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_URL": "cloudinary://api_key:api_secret@cloud_name"
      }
    },
    "cloudinary-smd": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/structured-metadata-mcp", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_URL": "cloudinary://api_key:api_secret@cloud_name"
      }
    },
    "cloudinary-analysis": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/analysis-mcp", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_URL": "cloudinary://api_key:api_secret@cloud_name"
      }
    }
  }
}

Opción 2: Uso de variables de entorno individuales

{
  "mcpServers": {
    "cloudinary-asset-mgmt": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/asset-management-mcp", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_CLOUD_NAME": "cloud_name",
        "CLOUDINARY_API_KEY": "api_key",
        "CLOUDINARY_API_SECRET": "api_secret"
      }
    }
  }
}

Opción 3: Uso de argumentos de línea de comandos

{
  "mcpServers": {
    "cloudinary-asset-mgmt": {
      "command": "npx",
      "args": [
        "-y", "--package", "@cloudinary/asset-management-mcp",
        "--",
        "mcp", "start",
        "--cloud-name", "cloud_name",
        "--api-key", "api_key",
        "--api-secret", "api_secret"
      ]
    }
  }
}

Configuración del servidor MediaFlows MCP

Para MediaFlows, usa la siguiente configuración:

{
  "mcpServers": {
    "mediaflows": {
      "url": "https://mediaflows.mcp.cloudinary.com/v2/mcp",
      "headers": {
        "cld-cloud-name": "cloud_name",
        "cld-api-key": "api_key",
        "cld-secret": "api_secret"
      }
    }
  }
}

Configuración avanzada del servidor local

Cada paquete npm admite opciones de configuración adicionales, además de los ejemplos básicos anteriores.

Ejecución como servidor HTTP

Para ejecutar un servidor MCP local mediante el transporte Streamable HTTP en lugar de stdio, usa el comando serve:

npx -y --package @cloudinary/asset-management-mcp -- mcp serve

El servidor escucha en http://localhost:2718/mcp. Puedes especificar un puerto personalizado:

npx -y --package @cloudinary/asset-management-mcp -- mcp serve --port 3000

El transporte SSE heredado sigue disponible mediante mcp start --transport sse (la misma opción --port, con el valor predeterminado 2718), pero está obsoleto. Usa mcp serve en las configuraciones nuevas:

npx -y --package @cloudinary/asset-management-mcp -- mcp start --transport sse

Opciones de configuración disponibles

Para ver todas las opciones de configuración disponibles para cualquier paquete:

npx -y --package @cloudinary/asset-management-mcp -- mcp start --help
npx -y --package @cloudinary/asset-management-mcp -- mcp serve --help

Lista completa de opciones disponibles (@cloudinary/asset-management-mcp; los demás paquetes admiten un subconjunto):

USAGE
  mcp start [--transport stdio|sse] [--port value] [--tool value]... [--mode dynamic]
            [--tool-annotations value] [--scope admin|builder|librarian]
            [--api-key value] [--api-secret value] [--oauth2 value]
            [--cloud-name value] [--server-url value] [--server-index value]
            [--region api|api-eu|api-ap] [--api-host value] [--mcp-apps value]
            [--log-level debug|warning|info|error] [--env value]...
  mcp serve [--port value] [--disable-static-auth] [--tool value]... [--mode dynamic]
            [--tool-annotations value] [--scope admin|builder|librarian]
            [--api-key value] [--api-secret value] [--oauth2 value]
            [--cloud-name value] [--server-url value] [--server-index value]
            [--region api|api-eu|api-ap] [--api-host value] [--mcp-apps value]
            [--log-level debug|warning|info|error] [--env value]...

COMMANDS
  start  Run the MCP server (stdio by default)
  serve  Run the MCP server with Streamable HTTP transport

FLAGS
  --transport              start only: the transport to use
                           [stdio|sse, default = stdio; sse is deprecated]
  --port                   The port to listen on [default = 2718]
  --disable-static-auth    serve only: disable static authentication, allowing
                           credentials to be passed via request headers only
  --tool...                Specify tools to mount on the server (repeatable)
  --mode                   dynamic: expose list_tools, describe_tool_input, and
                           execute_tool instead of individual tools [dynamic]
  --tool-annotations       Filter tools by annotations (comma-separated:
                           readOnly, destructive, idempotent, openWorld)
  --scope                  Mount tools/resources that match given scope
                           (repeatable) [admin|builder|librarian]
  --api-key                Sets the api_key auth field for the API
  --api-secret             Sets the api_secret auth field for the API
  --oauth2                 Sets the oauth2 auth field for the API
  --cloud-name             Allows setting the cloud_name parameter for all
                           supported operations
  --server-url             Overrides the default server URL used by the SDK
  --server-index           Selects a predefined server used by the SDK
  --region                 Sets the region variable for url substitution
                           [api|api-eu|api-ap]
  --api-host               Sets the host variable for url substitution
  --mcp-apps               Enable MCP Apps (interactive UI): bare flag or
                           all/true, none/false, or a comma-separated list of
                           asset-gallery,asset-details,asset-upload
  --log-level              The log level to use for the server
                           [debug|warning|info|error, default = info]
  --env...                 Environment variables made available to the server
  -h, --help               Print help information and exit

Depuración

Para depurar detalladamente las cargas útiles de red, usa la variable de entorno CLOUDINARY_DEBUG:

CLOUDINARY_DEBUG=true npx -y --package @cloudinary/asset-management-mcp -- mcp start

Puedes combinar el modo de depuración con otras opciones para solucionar problemas de forma exhaustiva:

CLOUDINARY_DEBUG=true npx -y --package @cloudinary/asset-management-mcp -- mcp serve --log-level debug

Nota: Estas opciones de configuración se aplican a todos los paquetes MCP locales:

  • @cloudinary/asset-management-mcp
  • @cloudinary/environment-config-mcp
  • @cloudinary/structured-metadata-mcp
  • @cloudinary/analysis-mcp

Autenticación

Al ejecutar servidores MCP localmente, puedes configurar la autenticación de varias maneras:

Opción 1: Variables de entorno individuales (recomendado)

export CLOUDINARY_CLOUD_NAME="cloud_name"
export CLOUDINARY_API_KEY="api_key"
export CLOUDINARY_API_SECRET="api_secret"

Opción 2: Variable de entorno CLOUDINARY_URL

export CLOUDINARY_URL="cloudinary://api_key:api_secret@cloud_name"

Opción 3: Argumentos de línea de comandos

Pasa las credenciales directamente como argumentos (consulta los ejemplos de configuración anteriores).

Puedes encontrar tus credenciales de Cloudinary en el panel de control de Cloudinary, en Settings > Security.

Funciones por servidor

Servidor de gestión de recursos

  • Carga y gestiona recursos multimedia (imágenes, vídeos y archivos sin procesar)
  • Busca y organiza recursos con filtros avanzados y búsqueda visual
  • Genera imágenes nuevas con IA a partir de indicaciones de texto o imágenes de referencia y las guarda directamente en tu cuenta
  • Gestiona operaciones y transformaciones de recursos
  • Gestiona carpetas, etiquetas y relaciones entre recursos
  • Genera archivos comprimidos y enlaces de descarga

Servidor de configuración del entorno

  • Crea y gestiona transformaciones con nombre y ajustes preestablecidos de carga
  • Gestiona perfiles de transmisión y activadores (notificaciones de webhook)
  • Configura asignaciones de carga

Servidor de metadatos estructurados

  • Crea y gestiona campos de metadatos estructurados
  • Configura reglas condicionales de metadatos y validación
  • Gestiona valores de fuentes de datos para campos de metadatos de tipo lista
  • Organiza y busca configuraciones de metadatos

Servidor de análisis

  • Análisis de contenido basado en IA, incluidos el etiquetado, la moderación y la generación de subtítulos
  • Detección y reconocimiento de objetos con varios modelos de IA
  • Análisis de calidad de imagen y detección de marcas de agua
  • Moderación de contenido y análisis de seguridad
  • Capacidades de detección de moda, texto y anatomía
  • Detección de logotipos y clasificación de productos (tienda)

Servidor MediaFlows

  • Crea y gestiona automatizaciones de flujos de trabajo mediante lenguaje natural
  • Consulta las automatizaciones de PowerFlow existentes en tu entorno
  • Crea lógica condicional basada en metadatos, etiquetas y propiedades de recursos
  • Automatiza los flujos de trabajo de moderación, aprobación y notificación de recursos
  • Depura y comprende las configuraciones de automatización existentes

¿Necesitas acceso a más herramientas de Cloudinary?

Seguimos añadiendo más funciones a estos servidores MCP. Si quieres dejar comentarios, informar de un error o solicitar una función, abre una incidencia en este repositorio.

Solución de problemas

«La respuesta de Claude se interrumpió...»

Si ves este mensaje, es probable que Claude haya alcanzado el límite de longitud del contexto y se haya detenido a mitad de la respuesta. Esto ocurre con mayor frecuencia en servidores que activan muchas llamadas encadenadas a herramientas, como el servidor de gestión de recursos cuando se muestran listas extensas de recursos.

Para reducir la probabilidad de que ocurra este problema:

  • Procura ser específico y mantener tus consultas concisas.
  • Si una sola solicitud llama a varias herramientas, intenta dividirla en varias llamadas más pequeñas para mantener breves las respuestas.
  • Usa parámetros de filtrado para limitar el alcance de las búsquedas y los listados de recursos.

Problemas de autenticación

Asegúrate de que tus credenciales de Cloudinary estén configuradas correctamente y tengan los permisos necesarios para las operaciones que quieres realizar.

Funciones de pago

Algunas funciones pueden requerir un plan de pago de Cloudinary. Asegúrate de que tu cuenta de Cloudinary tenga el nivel de suscripción necesario para las funciones que quieras usar, como:

  • Funciones avanzadas de análisis con IA
  • Uso de la API de gran volumen
  • Capacidades avanzadas de transformación

Licencia

Publicado bajo la licencia MIT. Consulta el archivo LICENSE para obtener más información.