Cloudinary

공식

Cloudinary의 미디어 관리 플랫폼을 자연어로 상호작용합니다.

Cloudinary MCP(으)로 무엇을 할 수 있나요?

미디어 업로드 및 관리 — 이미지, 동영상, 원본 파일을 업로드한 다음 폴더, 태그, 에셋 관계를 사용해 정리합니다.
에셋 검색 및 변환 — 고급 필터링으로 에셋을 검색하고 에셋 작업 및 변환을 적용합니다.
AI로 이미지 생성 — 텍스트 프롬프트나 참조 이미지로 새 이미지를 만들고 계정에 저장합니다.
미디어 콘텐츠 분석 — 에셋에 AI 태깅, 검토, 캡션 생성, 객체 감지, 워터마크 또는 품질 분석을 실행합니다.
환경 설정 구성 — 이름이 지정된 변환, 업로드 프리셋, 스트리밍 프로필, 웹훅 트리거를 생성합니다.
구조화된 메타데이터 관리 — 메타데이터 필드를 만들고, 유효성 검사 규칙을 설정하고, 목록 유형 필드의 데이터 소스 값을 관리합니다.

호스팅형 MCP 서버

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

Claude Code, Codex, Cursor 등에 설치됩니다

문서

Cloudinary MCP 서버

모델 컨텍스트 프로토콜(Model Context Protocol, MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위한 새로운 표준 프로토콜입니다. 이 저장소는 Cloudinary 미디어 관리 플랫폼을 위한 포괄적인 MCP 서버를 제공하며, Cursor 및 Claude와 같은 AI 애플리케이션에서 자연어를 사용해 미디어 자산을 직접 업로드, 생성, 변환, 분석 및 정리할 수 있도록 합니다.

이 MCP 서버를 사용하면 대화형 AI를 통해 업로드, 이미지와 동영상 생성 및 변환부터 자동 처리 파이프라인 구성, AI 기반 도구를 사용한 콘텐츠 분석, 구조화된 메타데이터를 활용한 자산 정리까지 전체 미디어 워크플로를 원활하게 관리할 수 있습니다. 미디어가 풍부한 애플리케이션을 구축하거나, 대규모 자산 라이브러리를 관리하거나, 콘텐츠 워크플로를 자동화할 때 이 서버를 통해 Cloudinary의 전체 미디어 최적화 및 관리 기능에 직접 액세스할 수 있습니다.

Cloudinary에서 사용할 수 있는 MCP 서버는 다음과 같습니다.

서버 이름	설명	원격 MCP 서버
자산 관리	미디어 자산을 업로드, 관리, 검색 및 변환하고, 텍스트 프롬프트나 참조 이미지를 사용해 AI로 새 이미지를 생성합니다	asset-management
환경 구성	Cloudinary 환경 설정, 업로드 프리셋 및 변환을 구성하고 관리합니다	environment-config
구조화된 메타데이터	자산을 더 효과적으로 정리하고 검색할 수 있도록 구조화된 메타데이터 필드를 생성, 관리 및 조회합니다	structured-metadata
분석	미디어 자산에 AI 기반 콘텐츠 분석, 검토 및 자동 태그 지정 기능을 활용합니다	analysis
MediaFlows	AI 기반 지원을 통해 이미지와 동영상의 로우코드 워크플로 자동화를 구축하고 관리합니다	mediaflows

문서

Cloudinary MCP 서버 사용에 관한 자세한 가이드, 튜토리얼 및 종합 문서는 다음을 참조하세요.

Cloudinary MCP 및 LLM 도구 문서 - Cloudinary를 AI/LLM 애플리케이션과 통합하는 전체 가이드
MediaFlows MCP 문서 - MediaFlows(MCP) 서버 사용을 위한 설정 안내 및 지침

설치

원격 MCP 서버(권장)

원격 MCP 서버는 Cloudinary에서 호스팅하며 즉시 사용할 수 있습니다. 로컬 설치가 필요하지 않습니다.

로컬 MCP 서버

로컬 MCP 서버는 npm 패키지를 사용해 컴퓨터에서 실행됩니다. 더 많은 제어 권한이나 사용자 지정이 필요한 경우 이 옵션을 선택하세요.

참고: 설치 후 실제 자격 증명으로 환경 변수(CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET)를 구성해야 합니다.

Docker 이미지

Cloudinary MCP 서버의 공식 Docker 이미지는 Docker Hub에서 제공되며, 로컬 또는 클라우드 환경에서 MCP 서버를 실행할 수 있는 컨테이너 배포 옵션을 제공합니다.

Docker Hub에서 사용 가능: Cloudinary MCP Docker 이미지

Docker 이미지를 사용하면 다음과 같은 이점이 있습니다.

격리된 환경 - 시스템 종속성에 영향을 주지 않고 컨테이너에서 MCP 서버를 실행합니다
간편한 배포 - 최소한의 구성만으로 빠르게 설정할 수 있습니다
일관된 런타임 - 서로 다른 컴퓨터와 플랫폼에서 동일한 환경을 보장합니다
확장성 - 여러 인스턴스를 쉽게 배포하거나 컨테이너 오케스트레이션 시스템에 통합할 수 있습니다

Docker 이미지를 사용하려면 시스템에 Docker가 설치되어 있는지 확인하고, 컨테이너를 실행할 때 Cloudinary 자격 증명을 환경 변수로 전달하세요. 구체적인 사용 방법은 Docker Hub의 각 Docker 이미지 문서를 참조하세요.

구성 예시

원격 MCP 서버 구성

원격 서버는 Cloudinary에서 호스팅되며 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"
    }
  }
}

전송 방식: 원격 서버는 두 개의 엔드포인트를 지원합니다. /mcp(Streamable HTTP, 권장, 상태 비저장)와 /sse(SSE, 사용 중단 예정, 이전 버전과의 호환성을 위해 유지)입니다. /sse 엔드포인트는 /mcp의 별칭으로 POST 요청도 허용하므로, /sse에 Streamable HTTP를 보내는 클라이언트도 작동합니다. 새 구성에는 /mcp를 사용하세요.

인증을 사용하는 원격 MCP 서버

Cloudinary에서 호스팅하는 원격 MCP 서버는 기본적으로 OAuth2를 사용해 인증합니다. 헤더를 통해 API 키로 인증할 수도 있습니다.

CLOUDINARY_URL 사용(가장 간단한 방법)

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

개별 헤더 사용

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

사용자 지정 구성 사용

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

디버그 헤더 사용

도구 결과에 API 속도 제한 헤더와 요청 ID를 표시하려면 헤더 임베딩을 활성화하세요.

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

각 도구 결과에는 속도 제한 및 요청 추적 정보가 포함된 _headers 필드가 포함됩니다.

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

로컬 MCP 서버 구성

로컬 서버는 npm 패키지를 사용해 컴퓨터에서 실행됩니다.

옵션 1: CLOUDINARY_URL 환경 변수 사용(권장)

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

옵션 2: 개별 환경 변수 사용

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

옵션 3: 명령줄 인수 사용

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

MediaFlows MCP 서버 구성

MediaFlows에는 다음 구성을 사용하세요.

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

고급 로컬 서버 구성

각 npm 패키지는 위의 기본 설정 예시 외에도 추가 구성 옵션을 지원합니다.

HTTP 서버로 실행

stdio 대신 Streamable HTTP 전송을 사용해 로컬 MCP 서버를 실행하려면 serve 명령을 사용하세요.

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

서버는 http://localhost:2718/mcp에서 수신 대기합니다. 사용자 지정 포트를 지정할 수 있습니다.

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

기존 SSE 전송은 mcp start --transport sse을 통해 계속 사용할 수 있습니다(동일한 --port 플래그, 기본값 2718). 하지만 사용 중단 예정입니다. 새 구성에는 mcp serve을 사용하세요.

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

사용 가능한 구성 옵션

패키지의 사용 가능한 모든 구성 옵션을 확인하려면 다음을 실행하세요.

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

사용 가능한 플래그 전체 목록(@cloudinary/asset-management-mcp; 다른 패키지는 일부만 지원):

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

디버깅

자세한 네트워크 페이로드 디버깅에는 CLOUDINARY_DEBUG 환경 변수를 사용하세요.

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

포괄적인 문제 해결을 위해 디버그 모드를 다른 옵션과 함께 사용할 수 있습니다.

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

참고: 이 구성 옵션은 모든 로컬 MCP 패키지에 적용됩니다.

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

인증

MCP 서버를 로컬에서 실행할 때는 여러 방법으로 인증을 구성할 수 있습니다.

옵션 1: 개별 환경 변수(권장)

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

옵션 2: CLOUDINARY_URL 환경 변수

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

옵션 3: 명령줄 인수

자격 증명을 인수로 직접 전달하세요(위의 구성 예시 참조).

Cloudinary 자격 증명은 Cloudinary Console Dashboard의 Settings > Security에서 확인할 수 있습니다.

서버별 기능

자산 관리 서버

미디어 자산(이미지, 동영상, 원시 파일)을 업로드하고 관리합니다
고급 필터링 및 시각적 검색으로 자산을 검색하고 정리합니다
텍스트 프롬프트나 참조 이미지를 사용해 AI로 새 이미지를 생성하고 계정에 바로 저장합니다
자산 작업 및 변환을 처리합니다
폴더, 태그 및 자산 관계를 관리합니다
아카이브와 다운로드 링크를 생성합니다

환경 구성 서버

이름이 지정된 변환 및 업로드 프리셋을 생성하고 관리합니다
스트리밍 프로필과 트리거(웹훅 알림)를 관리합니다
업로드 매핑을 설정합니다

구조화된 메타데이터 서버

구조화된 메타데이터 필드를 생성하고 관리합니다
조건부 메타데이터 규칙 및 유효성 검사를 구성합니다
목록 유형 메타데이터 필드의 데이터 소스 값을 관리합니다
메타데이터 구성을 정리하고 검색합니다

분석 서버

태그 지정, 검토 및 캡션 생성을 포함한 AI 기반 콘텐츠 분석
여러 AI 모델을 사용한 객체 감지 및 인식
이미지 품질 분석 및 워터마크 감지
콘텐츠 검토 및 안전성 분석
패션, 텍스트 및 해부학적 요소 감지 기능
로고 감지 및 제품(쇼핑) 분류

MediaFlows 서버

자연어를 사용해 워크플로 자동화를 구축하고 관리합니다
환경의 기존 PowerFlow 자동화를 조회합니다
메타데이터, 태그 및 자산 속성을 기반으로 조건부 로직을 생성합니다
자산 검토, 승인 및 알림 워크플로를 자동화합니다
기존 자동화 구성을 디버깅하고 파악합니다

더 많은 Cloudinary 도구에 액세스해야 하나요?

이 MCP 서버에 더 많은 기능을 계속 추가하고 있습니다. 의견을 남기거나 버그를 신고하거나 기능을 요청하려면 이 저장소에 이슈를 등록하세요.

문제 해결

"Claude's response was interrupted..."

이 메시지가 표시되면 Claude가 컨텍스트 길이 제한에 도달해 응답 도중에 중단되었을 가능성이 높습니다. 자산 관리 서버에서 대규모 자산 목록을 처리하는 경우처럼 여러 도구 호출을 연쇄적으로 실행하는 서버에서 이런 문제가 가장 자주 발생합니다.

이 문제가 발생할 가능성을 줄이려면 다음을 시도하세요.

구체적으로 요청하고 질문을 간결하게 작성하세요.
한 번의 요청으로 여러 도구를 호출한다면 응답을 짧게 유지할 수 있도록 여러 개의 작은 도구 호출로 나누세요.
필터링 매개변수를 사용해 자산 검색 및 목록의 범위를 제한하세요.

인증 문제

Cloudinary 자격 증명이 올바르게 구성되어 있고 수행하려는 작업에 필요한 권한이 있는지 확인하세요.

유료 기능

일부 기능을 사용하려면 유료 Cloudinary 요금제가 필요할 수 있습니다. 다음과 같이 사용하려는 기능에 필요한 구독 등급을 Cloudinary 계정에서 이용할 수 있는지 확인하세요.

고급 AI 분석 기능
대량의 API 사용
고급 변환 기능

라이선스

MIT License에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.