Cloudinary

oficial

Interaja com a plataforma de gerenciamento de mídia do Cloudinary usando linguagem natural.

GitHub
10

O que você pode fazer com Cloudinary MCP?

  • Fazer upload e gerenciar mídias — Faça upload de imagens, vídeos e arquivos brutos e, em seguida, organize-os com pastas, tags e relações entre ativos.
  • Pesquisar e transformar ativos — Pesquise ativos com filtros avançados e aplique operações e transformações aos ativos.
  • Gerar imagens com IA — Crie novas imagens a partir de prompts de texto ou imagens de referência e salve-as na sua conta.
  • Analisar conteúdo de mídia — Execute marcação com IA, moderação, geração de legendas, detecção de objetos e análise de marca d’água ou qualidade nos ativos.
  • Configurar definições do ambiente — Crie transformações nomeadas, predefinições de upload, perfis de streaming e gatilhos de webhook.
  • Gerenciar metadados estruturados — Crie campos de metadados, defina regras de validação e gerencie valores de fontes de dados para campos do tipo lista.

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidores MCP do Cloudinary

O Model Context Protocol (MCP) é um novo protocolo padronizado para gerenciar o contexto entre grandes modelos de linguagem (LLMs) e sistemas externos. Este repositório oferece servidores MCP abrangentes para a plataforma de gerenciamento de mídia do Cloudinary, permitindo usar linguagem natural para carregar, gerar, transformar, analisar e organizar seus ativos de mídia diretamente em aplicativos de IA, como Cursor e Claude.

Com esses servidores MCP, você pode gerenciar perfeitamente todo o seu fluxo de trabalho de mídia por meio de IA conversacional — desde carregar, gerar e transformar imagens e vídeos até configurar pipelines de processamento automatizado, analisar conteúdo com ferramentas baseadas em IA e organizar ativos com metadados estruturados. Seja para criar aplicativos com conteúdo de mídia, gerenciar grandes bibliotecas de ativos ou automatizar fluxos de trabalho de conteúdo, esses servidores oferecem acesso direto a todo o conjunto de recursos de otimização e gerenciamento de mídia do Cloudinary.

Os seguintes servidores MCP estão disponíveis para o Cloudinary:

Nome do servidorDescriçãoServidor MCP remoto
Gerenciamento de ativosCarregue, gerencie, pesquise e transforme seus ativos de mídia, e gere novas imagens com IA a partir de prompts de texto ou imagens de referênciaasset-management
Configuração do ambienteConfigure e gerencie as definições do seu ambiente Cloudinary, predefinições de carregamento e transformaçõesenvironment-config
Metadados estruturadosCrie, gerencie e consulte campos de metadados estruturados para aprimorar a organização e a capacidade de pesquisa dos ativosstructured-metadata
AnáliseAproveite os recursos de análise de conteúdo, moderação e marcação automática com tecnologia de IA para seus ativos de mídiaanalysis
MediaFlowsCrie e gerencie automações de fluxo de trabalho low-code para imagens e vídeos com assistência baseada em IAmediaflows

Sumário

Documentação

Para obter guias detalhados, tutoriais e documentação abrangente sobre como usar os servidores MCP do Cloudinary:

Instalação

Servidores MCP remotos (recomendado)

Os servidores MCP remotos são hospedados pelo Cloudinary e estão prontos para uso imediato. Não é necessária instalação local.

Servidores MCP locais

Os servidores MCP locais são executados na sua máquina usando pacotes npm. Escolha esta opção se precisar de mais controle ou personalização.

Observação: após a instalação, você precisará configurar suas variáveis de ambiente (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET) com suas credenciais reais.

Imagens Docker

As imagens Docker oficiais dos servidores MCP do Cloudinary estão disponíveis no Docker Hub, oferecendo uma opção de implantação em contêineres para executar servidores MCP localmente ou em ambientes de nuvem.

Disponível no Docker Hub: Imagens Docker do MCP do Cloudinary

As imagens Docker oferecem vários benefícios:

  • Ambientes isolados - Execute servidores MCP em contêineres sem afetar as dependências do seu sistema
  • Implantação fácil - Configuração rápida com o mínimo de ajustes necessários
  • Ambiente de execução consistente - Garante o mesmo ambiente em diferentes máquinas e plataformas
  • Escalabilidade - Implante facilmente várias instâncias ou integre-as a sistemas de orquestração de contêineres

Para usar imagens Docker, verifique se o Docker está instalado no seu sistema e passe suas credenciais do Cloudinary como variáveis de ambiente ao executar os contêineres. Consulte a documentação de cada imagem Docker no Docker Hub para ver instruções específicas de uso.

Exemplos de configuração

Configuração de servidores MCP remotos

Os servidores remotos são hospedados pelo Cloudinary e acessados por 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: os servidores remotos oferecem suporte a dois endpoints — /mcp (Streamable HTTP, recomendado, sem estado) e /sse (SSE, obsoleto, mantido para compatibilidade com versões anteriores). O endpoint /sse também aceita solicitações POST como alias de /mcp, portanto, clientes que enviam Streamable HTTP para /sse funcionarão. Use /mcp em novas configurações.

Servidores MCP remotos com autenticação

Os servidores MCP remotos hospedados pelo Cloudinary usam OAuth2 por padrão para autenticação. Você também pode se autenticar usando chaves de API por meio de cabeçalhos:

Usando CLOUDINARY_URL (mais simples)

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

Usando cabeçalhos individuais

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

Com configuração 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"
      }
    }
  }
}

Com cabeçalhos de depuração

Para exibir cabeçalhos de limite de taxa da API e IDs de solicitação nos resultados das ferramentas, habilite a inclusão de cabeçalhos:

{
  "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 ferramenta incluirá um campo _headers com informações sobre limites de taxa e rastreamento de solicitações:

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

Configuração de servidores MCP locais

Os servidores locais são executados na sua máquina usando pacotes npm:

Opção 1: usando a variável de ambiente 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"
      }
    }
  }
}

Opção 2: usando variáveis de ambiente individuais

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

Opção 3: usando argumentos de linha de comando

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

Configuração do servidor MCP do MediaFlows

Para o MediaFlows, use a seguinte configuração:

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

Configuração avançada do servidor local

Cada pacote npm oferece opções de configuração adicionais além dos exemplos básicos de configuração acima.

Executar como servidor HTTP

Para executar um servidor MCP local usando o transporte Streamable HTTP em vez de stdio, use o comando serve:

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

O servidor escuta em http://localhost:2718/mcp. Você pode especificar uma porta personalizada:

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

O transporte SSE legado ainda está disponível por meio de mcp start --transport sse (mesma opção --port, padrão 2718), mas está obsoleto. Use mcp serve em novas configurações:

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

Opções de configuração disponíveis

Para ver todas as opções de configuração disponíveis para qualquer pacote:

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

Lista completa das opções disponíveis (@cloudinary/asset-management-mcp; outros pacotes oferecem suporte a um 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

Depuração

Para depurar detalhadamente os payloads de rede, use a variável de ambiente CLOUDINARY_DEBUG:

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

Você pode combinar o modo de depuração com outras opções para solucionar problemas de forma abrangente:

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

Observação: estas opções de configuração se aplicam a todos os pacotes MCP locais:

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

Autenticação

Ao executar servidores MCP localmente, a autenticação pode ser configurada de várias maneiras:

Opção 1: variáveis de ambiente individuais (recomendado)

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

Opção 2: variável de ambiente CLOUDINARY_URL

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

Opção 3: argumentos de linha de comando

Passe as credenciais diretamente como argumentos (consulte os exemplos de configuração acima)

Você pode encontrar suas credenciais do Cloudinary no Painel do Cloudinary Console, em Settings > Security.

Recursos por servidor

Servidor de gerenciamento de ativos

  • Carregue e gerencie ativos de mídia (imagens, vídeos e arquivos brutos)
  • Pesquise e organize ativos com filtragem avançada e pesquisa visual
  • Gere novas imagens com IA a partir de prompts de texto ou imagens de referência, salvando-as diretamente na sua conta
  • Execute operações e transformações em ativos
  • Gerencie pastas, tags e relações entre ativos
  • Gere arquivos compactados e links para download

Servidor de configuração do ambiente

  • Crie e gerencie transformações nomeadas e predefinições de carregamento
  • Gerencie perfis de streaming e acionadores (notificações por webhook)
  • Configure mapeamentos de carregamento

Servidor de metadados estruturados

  • Crie e gerencie campos de metadados estruturados
  • Configure regras condicionais de metadados e validação
  • Gerencie valores de fontes de dados para campos de metadados do tipo lista
  • Organize e pesquise configurações de metadados

Servidor de análise

  • Análise de conteúdo com tecnologia de IA, incluindo marcação, moderação e geração de legendas
  • Detecção e reconhecimento de objetos com vários modelos de IA
  • Análise da qualidade de imagens e detecção de marcas d'água
  • Moderação de conteúdo e análise de segurança
  • Recursos de detecção de moda, texto e anatomia
  • Detecção de logotipos e classificação de produtos (loja)

Servidor MediaFlows

  • Crie e gerencie automações de fluxo de trabalho usando linguagem natural
  • Consulte automações PowerFlow existentes no seu ambiente
  • Crie lógica condicional com base em metadados, tags e propriedades dos ativos
  • Automatize fluxos de trabalho de moderação, aprovação e notificação de ativos
  • Depure e compreenda configurações de automação existentes

Precisa acessar mais ferramentas do Cloudinary?

Continuamos adicionando mais funcionalidades a esses servidores MCP. Se quiser enviar comentários, relatar um bug ou solicitar um recurso, abra uma issue neste repositório.

Solução de problemas

"A resposta do Claude foi interrompida..."

Se você vir esta mensagem, provavelmente o Claude atingiu o limite de tamanho do contexto e parou no meio da resposta. Isso acontece com mais frequência em servidores que acionam muitas chamadas encadeadas de ferramentas, como o servidor de gerenciamento de ativos com listagens extensas de ativos.

Para reduzir a probabilidade de encontrar esse problema:

  • Tente ser específico e manter suas consultas concisas.
  • Se uma única solicitação chamar várias ferramentas, tente dividi-la em várias chamadas menores para manter as respostas curtas.
  • Use parâmetros de filtragem para limitar o escopo das pesquisas e listagens de ativos.

Problemas de autenticação

Verifique se suas credenciais do Cloudinary estão configuradas corretamente e têm as permissões necessárias para as operações que você está tentando realizar.

Recursos pagos

Alguns recursos podem exigir um plano pago do Cloudinary. Verifique se sua conta do Cloudinary tem o nível de assinatura necessário para os recursos que você pretende usar, como:

  • Recursos avançados de análise com IA
  • Uso da API em alto volume
  • Recursos avançados de transformação

Licença

Licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.