Cloudinary

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

Cloudinary MCP 서버

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

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

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

서버 이름	설명	원격 MCP 서버
자산 관리	고급 검색 및 구성 기능으로 미디어 자산 업로드, 관리 및 변환	asset-management
환경 구성	Cloudinary 환경 설정, 업로드 프리셋 및 변환 구성 및 관리	environment-config
구조화된 메타데이터	향상된 자산 구성 및 검색 가능성을 위한 구조화된 메타데이터 필드 생성, 관리 및 쿼리	structured-metadata
분석	미디어 자산을 위한 AI 기반 콘텐츠 분석, 조정 및 자동 태그 지정 기능 활용	analysis
MediaFlows	AI 기반 지원으로 이미지 및 비디오를 위한 로우코드 워크플로우 자동화 구축 및 관리	mediaflows

목차

• 문서
• 설치
  • 원격 MCP 서버(권장)
  • 로컬 MCP 서버
  • Docker 이미지
• 구성 예시
  • 고급 로컬 서버 구성
• 인증
• 서버별 기능
• 더 많은 Cloudinary 도구가 필요하신가요?
• 문제 해결
• 유료 기능
• 라이선스

문서

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/sse"
    },
    "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", "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 패키지는 위의 기본 설정 예시 외에 추가 구성 옵션을 지원합니다.

SSE 서버로 실행

stdio 대신 Server-Sent Events(SSE) 전송을 사용하여 로컬 MCP 서버를 실행하려면:

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

사용자 지정 포트를 지정할 수 있습니다(기본값은 2718):

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

사용 가능한 구성 옵션

모든 패키지의 사용 가능한 구성 옵션을 보려면:

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

사용 가능한 전체 플래그 목록:

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

디버깅

자세한 네트워크 페이로드 디버깅을 위해 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 start --transport sse --log-level debug

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

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

인증

로컬에서 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 콘솔 대시보드의 설정 > 보안에서 찾을 수 있습니다.

서버별 기능

자산 관리 서버

• 미디어 자산(이미지, 비디오, 원시 파일) 업로드 및 관리
• 고급 필터링 기능으로 자산 검색 및 구성
• 자산 작업 및 변환 처리
• 폴더, 태그 및 자산 관계 관리
• 아카이브 및 다운로드 링크 생성

환경 구성 서버

• 업로드 프리셋 및 변환 설정 구성
• 스트리밍 프로필 및 웹훅 알림 관리
• 업로드 매핑 설정

구조화된 메타데이터 서버

• 구조화된 메타데이터 필드 생성 및 관리
• 조건부 메타데이터 규칙 및 검증 구성
• 메타데이터 구성 구성 및 검색
• 메타데이터 필드 관계 및 순서 처리

분석 서버

• 태그 지정, 조정 및 캡션 생성을 포함한 AI 기반 콘텐츠 분석
• 여러 AI 모델을 사용한 객체 감지 및 인식
• 이미지 품질 분석 및 워터마크 감지
• 콘텐츠 조정 및 안전 분석
• 패션, 텍스트 및 해부학 감지 기능

MediaFlows 서버

• 자연어를 사용한 워크플로우 자동화 구축 및 관리
• 환경의 기존 PowerFlow 자동화 쿼리
• 메타데이터, 태그 및 자산 속성을 기반으로 한 조건부 논리 생성
• 자산 조정, 승인 및 알림 워크플로우 자동화
• 기존 자동화 구성 디버그 및 이해

더 많은 Cloudinary 도구가 필요하신가요?

이 MCP 서버에 더 많은 기능을 계속 추가하고 있습니다. 피드백을 남기거나, 버그를 신고하거나, 기능 요청을 제공하려면 이 저장소에 이슈를 열어주세요.

문제 해결

"Claude의 응답이 중단되었습니다..."

이 메시지가 표시되면 Claude가 컨텍스트 길이 제한에 도달하여 응답 중간에 중단된 것입니다. 이는 대규모 자산 목록이 있는 자산 관리 서버와 같이 많은 체인 도구 호출을 트리거하는 서버에서 가장 자주 발생합니다.

이 문제가 발생할 가능성을 줄이려면:

• 구체적으로 작성하고 쿼리를 간결하게 유지하세요.
• 단일 요청이 여러 도구를 호출하는 경우 응답을 짧게 유지하기 위해 여러 개의 작은 도구 호출로 나누세요.
• 필터링 매개변수를 사용하여 자산 검색 및 목록의 범위를 제한하세요.

인증 문제

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

유료 기능

일부 기능은 유료 Cloudinary 요금제가 필요할 수 있습니다. 사용하려는 기능에 대해 Cloudinary 계정에 필요한 구독 수준이 있는지 확인하세요. 예:

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

라이선스

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