Cloudinary

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

Servidores MCP da Cloudinary

O Model Context Protocol (MCP) é um protocolo novo e padronizado para gerenciar o contexto entre modelos de linguagem de grande porte (LLMs) e sistemas externos. Este repositório fornece servidores MCP abrangentes para a plataforma de gerenciamento de mídia da Cloudinary, permitindo que você use linguagem natural para enviar, transformar, analisar e organizar seus ativos de mídia diretamente de aplicações 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 o upload e a transformação de imagens e vídeos, até a configuração de pipelines de processamento automatizados, análise de conteúdo com ferramentas alimentadas por IA e organização de ativos com metadados estruturados. Esteja você criando aplicações ricas em mídia, gerenciando grandes bibliotecas de ativos ou automatizando fluxos de trabalho de conteúdo, esses servidores fornecem acesso direto ao conjunto completo de recursos de otimização e gerenciamento de mídia da Cloudinary.

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

Nome do Servidor	Descrição	Servidor MCP Remoto
Gerenciamento de Ativos	Envie, gerencie e transforme seus ativos de mídia com recursos avançados de busca e organização	asset-management
Configuração de Ambiente	Configure e gerencie as configurações de ambiente da sua Cloudinary, predefinições de upload e transformações	environment-config
Metadados Estruturados	Crie, gerencie e consulte campos de metadados estruturados para melhor organização e capacidade de busca de ativos	structured-metadata
Análise	Aproveite a análise de conteúdo alimentada por IA, moderação e recursos de marcação automática para seus ativos de mídia	analysis
MediaFlows	Crie e gerencie automações de fluxo de trabalho low-code para imagens e vídeos com assistência alimentada por IA	mediaflows

Sumário

• Documentação
• Instalação
  • Servidores MCP Remotos (Recomendado)
  • Servidores MCP Locais
  • Imagens Docker
• Exemplos de Configuração
  • Configuração Avançada de Servidor Local
• Autenticação
• Recursos por Servidor
• Precisa de acesso a mais ferramentas da Cloudinary?
• Solução de Problemas
• Recursos Pagos
• Licença

Documentação

Para guias detalhados, tutoriais e documentação abrangente sobre o uso dos servidores MCP da Cloudinary:

• Documentação de Ferramentas MCP e LLM da Cloudinary — Guia completo para integrar a Cloudinary com aplicações de IA/LLM
• Documentação MCP do MediaFlows — Instruções de configuração e diretrizes para usar o servidor MediaFlows (MCP)

Instalação

Servidores MCP Remotos (Recomendado)

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

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: Você precisará configurar suas variáveis de ambiente (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET) com suas credenciais reais após a instalação.

Imagens Docker

Imagens Docker oficiais para os servidores MCP da Cloudinary estão disponíveis no Docker Hub, fornecendo uma opção de implantação em contêineres para executar servidores MCP localmente ou em ambientes de nuvem.

Disponíveis no Docker Hub: Imagens Docker MCP da 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 configuração necessária
• Runtime consistente — Garante o mesmo ambiente em diferentes máquinas e plataformas
• Escalabilidade — Implante facilmente várias instâncias ou integre-se a sistemas de orquestração de contêineres

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

Exemplos de Configuração

Configuração de Servidores MCP Remotos

Os servidores remotos são hospedados pela Cloudinary e acessados via 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/sse"
    },
    "mediaflows": {
      "url": "https://mediaflows.mcp.cloudinary.com/v2/mcp"
    }
  }
}

Transporte: Os servidores remotos suportam dois endpoints — /mcp (Streamable HTTP, recomendado, sem estado) e /sse (SSE, obsoleto, mantido para compatibilidade reversa). O endpoint /sse também aceita solicitações POST como um alias para /mcp, para que clientes que enviam Streamable HTTP para /sse funcionem. Use /mcp para novas configurações.

Servidores MCP Remotos com Autenticação

Os servidores MCP remotos hospedados pela Cloudinary usam OAuth2 por padrão para autenticação. Você também pode 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 incorporaçã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 de limite 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", "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 de Servidor Local

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

Executando como Servidor SSE

Para executar um servidor MCP local usando transporte Server-Sent Events (SSE) em vez de stdio:

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

Você pode especificar uma porta personalizada (o padrão é 2718):

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

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

Lista completa de sinalizadores disponíveis:

USAGE
  mcp start [--transport stdio|sse] [--port value] [--tool 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]
            [--log-level debug|warning|info|error] [--env value]...

FLAGS
  --transport       The transport to use for communicating with the server
                    [stdio|sse, default = stdio]
  --port            The port to use when the SSE transport is enabled
                    [default = 2718]
  --tool...         Specify tools to mount on the server (repeatable)
  --scope           Mount tools/resources that match given scope
                    [admin|builder|librarian]
  --api-key         Sets the apiKey auth field for the API
  --api-secret      Sets the apiSecret auth field for the API
  --oauth2          Sets the oauth2 auth field for the API
  --cloud-name      Allows setting the cloudName parameter for all 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
  --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 depuração detalhada de payload 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 solução de problemas abrangente:

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

Observação: Essas 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

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 (veja os exemplos de configuração acima)

Você pode encontrar suas credenciais da Cloudinary no seu Painel do Console da Cloudinary em Configurações > Segurança.

Recursos por Servidor

Servidor de Gerenciamento de Ativos

• Envie e gerencie ativos de mídia (imagens, vídeos, arquivos brutos)
• Busque e organize ativos com recursos avançados de filtragem
• Lide com operações e transformações de ativos
• Gerencie pastas, tags e relacionamentos de ativos
• Gere arquivos e links de download

Servidor de Configuração de Ambiente

• Configure predefinições de upload e configurações de transformação
• Gerencie perfis de streaming e notificações de webhook
• Configure mapeamentos de upload

Servidor de Metadados Estruturados

• Crie e gerencie campos de metadados estruturados
• Configure regras de metadados condicionais e validação
• Organize e busque configurações de metadados
• Lide com relacionamentos e ordenação de campos de metadados

Servidor de Análise

• Análise de conteúdo alimentada por IA, incluindo marcação, moderação e legendagem
• Detecção e reconhecimento de objetos com múltiplos modelos de IA
• Análise de qualidade de imagem e detecção de marca d'água
• Moderação de conteúdo e análise de segurança
• Recursos de detecção de moda, texto e anatomia

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 de ativos
• Automatize fluxos de trabalho de moderação, aprovação e notificação de ativos
• Depure e entenda configurações de automação existentes

Precisa de acesso a mais ferramentas da Cloudinary?

Estamos continuamente adicionando mais funcionalidades a esses servidores MCP. Se você quiser deixar feedback, relatar um bug ou fornecer uma solicitação de recurso, abra uma issue neste repositório.

Solução de Problemas

"A resposta do Claude foi interrompida..."

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

Para reduzir a chance de encontrar esse problema:

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

Problemas de Autenticação

Certifique-se de que suas credenciais da Cloudinary estejam configuradas corretamente e tenham as permissões necessárias para as operações que você está tentando realizar.

Recursos Pagos

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

• Recursos avançados de análise de IA
• Uso de 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.