Cloudinary

chính thức

Tương tác với nền tảng quản lý phương tiện của Cloudinary bằng ngôn ngữ tự nhiên.

GitHub
10

Bạn có thể làm gì với Cloudinary MCP?

  • Tải lên và quản lý nội dung đa phương tiện — Tải lên hình ảnh, video và tệp thô, sau đó sắp xếp chúng bằng thư mục, thẻ và mối quan hệ giữa các tài sản.
  • Tìm kiếm và biến đổi tài sản — Tìm kiếm tài sản bằng bộ lọc nâng cao và áp dụng các thao tác cũng như phép biến đổi cho tài sản.
  • Tạo hình ảnh bằng AI — Tạo hình ảnh mới từ câu lệnh văn bản hoặc hình ảnh tham chiếu và lưu vào tài khoản của bạn.
  • Phân tích nội dung đa phương tiện — Chạy các tính năng gắn thẻ bằng AI, kiểm duyệt, tạo chú thích, phát hiện đối tượng và phân tích hình mờ hoặc chất lượng trên tài sản.
  • Cấu hình cài đặt môi trường — Tạo các phép biến đổi có tên, cấu hình tải lên, hồ sơ phát trực tuyến và trình kích hoạt webhook.
  • Quản lý siêu dữ liệu có cấu trúc — Tạo các trường siêu dữ liệu, đặt quy tắc xác thực và quản lý giá trị nguồn dữ liệu cho các trường dạng danh sách.

Máy chủ MCP được lưu trữ

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

Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác

Tài liệu

Cloudinary MCP Servers

Model Context Protocol (MCP) là một giao thức mới, được chuẩn hóa để quản lý ngữ cảnh giữa các mô hình ngôn ngữ lớn (LLM) và hệ thống bên ngoài. Kho lưu trữ này cung cấp các máy chủ MCP toàn diện cho nền tảng quản lý phương tiện của Cloudinary, cho phép bạn dùng ngôn ngữ tự nhiên để tải lên, tạo, biến đổi, phân tích và sắp xếp tài sản phương tiện trực tiếp từ các ứng dụng AI như Cursor và Claude.

Với các máy chủ MCP này, bạn có thể quản lý liền mạch toàn bộ quy trình làm việc với phương tiện thông qua AI hội thoại — từ tải lên, tạo và biến đổi hình ảnh, video đến cấu hình quy trình xử lý tự động, phân tích nội dung bằng các công cụ hỗ trợ AI và sắp xếp tài sản bằng siêu dữ liệu có cấu trúc. Dù bạn đang xây dựng ứng dụng giàu nội dung phương tiện, quản lý thư viện tài sản lớn hay tự động hóa quy trình nội dung, các máy chủ này đều cung cấp quyền truy cập trực tiếp vào toàn bộ bộ tính năng tối ưu hóa và quản lý phương tiện của Cloudinary.

Cloudinary cung cấp các máy chủ MCP sau:

Tên máy chủMô tảMáy chủ MCP từ xa
Quản lý tài sảnTải lên, quản lý, tìm kiếm và biến đổi tài sản phương tiện, đồng thời tạo hình ảnh mới bằng AI từ lời nhắc văn bản hoặc hình ảnh tham chiếuasset-management
Cấu hình môi trườngCấu hình và quản lý cài đặt môi trường Cloudinary, cấu hình tải lên và các phép biến đổienvironment-config
Siêu dữ liệu có cấu trúcTạo, quản lý và truy vấn các trường siêu dữ liệu có cấu trúc để cải thiện việc sắp xếp và khả năng tìm kiếm tài sảnstructured-metadata
Phân tíchTận dụng các khả năng phân tích nội dung, kiểm duyệt và tự động gắn thẻ bằng AI cho tài sản phương tiệnanalysis
MediaFlowsXây dựng và quản lý quy trình tự động hóa ít mã cho hình ảnh và video với sự hỗ trợ của AImediaflows

Mục lục

Tài liệu

Để xem hướng dẫn chi tiết, bài hướng dẫn và tài liệu toàn diện về cách sử dụng máy chủ MCP của Cloudinary:

Cài đặt

Máy chủ MCP từ xa (Khuyến nghị)

Máy chủ MCP từ xa do Cloudinary lưu trữ và sẵn sàng sử dụng ngay. Không cần cài đặt cục bộ.

Máy chủ MCP cục bộ

Máy chủ MCP cục bộ chạy trên máy của bạn bằng các gói npm. Hãy chọn tùy chọn này nếu bạn cần kiểm soát hoặc tùy chỉnh nhiều hơn.

Lưu ý: Sau khi cài đặt, bạn cần cấu hình các biến môi trường (CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET) bằng thông tin xác thực thực tế của mình.

Docker Images

Docker image chính thức cho máy chủ MCP của Cloudinary có trên Docker Hub, cung cấp tùy chọn triển khai bằng container để chạy máy chủ MCP cục bộ hoặc trong môi trường đám mây.

Có trên Docker Hub: Docker image MCP của Cloudinary

Docker image mang lại một số lợi ích:

  • Môi trường biệt lập - Chạy máy chủ MCP trong container mà không ảnh hưởng đến các phần phụ thuộc của hệ thống
  • Triển khai dễ dàng - Thiết lập nhanh chóng với yêu cầu cấu hình tối thiểu
  • Môi trường chạy nhất quán - Đảm bảo môi trường giống nhau trên các máy và nền tảng khác nhau
  • Khả năng mở rộng - Dễ dàng triển khai nhiều phiên bản hoặc tích hợp vào các hệ thống điều phối container

Để sử dụng Docker image, hãy đảm bảo Docker đã được cài đặt trên hệ thống và truyền thông tin xác thực Cloudinary dưới dạng biến môi trường khi chạy container. Xem tài liệu Docker image tương ứng trên Docker Hub để biết hướng dẫn sử dụng cụ thể.

Ví dụ cấu hình

Cấu hình máy chủ MCP từ xa

Máy chủ từ xa do Cloudinary lưu trữ và được truy cập qua 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"
    }
  }
}

Giao thức truyền tải: Máy chủ từ xa hỗ trợ hai endpoint — /mcp (Streamable HTTP, được khuyến nghị, không trạng thái) và /sse (SSE, đã lỗi thời nhưng vẫn được giữ để tương thích ngược). Endpoint /sse cũng chấp nhận các yêu cầu POST như một bí danh của /mcp, vì vậy các ứng dụng khách gửi Streamable HTTP đến /sse vẫn hoạt động. Hãy dùng /mcp cho cấu hình mới.

Máy chủ MCP từ xa có xác thực

Máy chủ MCP từ xa do Cloudinary lưu trữ mặc định sử dụng OAuth2 để xác thực. Bạn cũng có thể xác thực bằng khóa API thông qua header:

Sử dụng CLOUDINARY_URL (Đơn giản nhất)

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

Sử dụng từng header riêng lẻ

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

Với cấu hình tùy chỉnh

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

Với header gỡ lỗi

Để hiển thị header giới hạn tốc độ API và ID yêu cầu trong kết quả công cụ, hãy bật tính năng nhúng header:

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

Mỗi kết quả công cụ sẽ bao gồm trường _headers chứa thông tin giới hạn tốc độ và theo dõi yêu cầu:

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

Cấu hình máy chủ MCP cục bộ

Máy chủ cục bộ chạy trên máy của bạn bằng các gói npm:

Tùy chọn 1: Sử dụng biến môi trường CLOUDINARY_URL (Khuyến nghị)

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

Tùy chọn 2: Sử dụng từng biến môi trường riêng lẻ

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

Tùy chọn 3: Sử dụng đối số dòng lệnh

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

Cấu hình máy chủ MediaFlows MCP

Đối với MediaFlows, hãy sử dụng cấu hình sau:

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

Cấu hình máy chủ cục bộ nâng cao

Mỗi gói npm hỗ trợ thêm các tùy chọn cấu hình ngoài những ví dụ thiết lập cơ bản ở trên.

Chạy dưới dạng máy chủ HTTP

Để chạy máy chủ MCP cục bộ bằng giao thức truyền tải Streamable HTTP thay vì stdio, hãy dùng lệnh serve:

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

Máy chủ lắng nghe trên http://localhost:2718/mcp. Bạn có thể chỉ định cổng tùy chỉnh:

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

Giao thức truyền tải SSE cũ vẫn có thể dùng qua mcp start --transport sse (cùng cờ --port, mặc định là 2718), nhưng đã lỗi thời. Hãy dùng mcp serve cho cấu hình mới:

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

Các tùy chọn cấu hình hiện có

Để xem tất cả tùy chọn cấu hình hiện có cho bất kỳ gói nào:

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

Danh sách đầy đủ các cờ hiện có (@cloudinary/asset-management-mcp; các gói khác hỗ trợ một tập hợp con):

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

Gỡ lỗi

Để gỡ lỗi chi tiết tải trọng mạng, hãy dùng biến môi trường CLOUDINARY_DEBUG:

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

Bạn có thể kết hợp chế độ gỡ lỗi với các tùy chọn khác để khắc phục sự cố toàn diện:

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

Lưu ý: Các tùy chọn cấu hình này áp dụng cho tất cả gói MCP cục bộ:

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

Xác thực

Khi chạy máy chủ MCP cục bộ, bạn có thể cấu hình xác thực theo một số cách:

Tùy chọn 1: Các biến môi trường riêng lẻ (Khuyến nghị)

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

Tùy chọn 2: Biến môi trường CLOUDINARY_URL

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

Tùy chọn 3: Đối số dòng lệnh

Truyền trực tiếp thông tin xác thực dưới dạng đối số (xem các ví dụ cấu hình ở trên)

Bạn có thể tìm thông tin xác thực Cloudinary trong Bảng điều khiển Cloudinary tại Settings > Security.

Tính năng theo máy chủ

Máy chủ quản lý tài sản

  • Tải lên và quản lý tài sản phương tiện (hình ảnh, video, tệp thô)
  • Tìm kiếm và sắp xếp tài sản bằng bộ lọc nâng cao và tìm kiếm trực quan
  • Tạo hình ảnh mới bằng AI từ lời nhắc văn bản hoặc hình ảnh tham chiếu, lưu trực tiếp vào tài khoản của bạn
  • Thực hiện các thao tác và phép biến đổi trên tài sản
  • Quản lý thư mục, thẻ và mối quan hệ giữa các tài sản
  • Tạo tệp lưu trữ và liên kết tải xuống

Máy chủ cấu hình môi trường

  • Tạo và quản lý các phép biến đổi có tên và cấu hình tải lên
  • Quản lý hồ sơ phát trực tuyến và trình kích hoạt (thông báo webhook)
  • Thiết lập ánh xạ tải lên

Máy chủ siêu dữ liệu có cấu trúc

  • Tạo và quản lý các trường siêu dữ liệu có cấu trúc
  • Cấu hình quy tắc siêu dữ liệu có điều kiện và xác thực
  • Quản lý giá trị nguồn dữ liệu cho các trường siêu dữ liệu dạng danh sách
  • Sắp xếp và tìm kiếm cấu hình siêu dữ liệu

Máy chủ phân tích

  • Phân tích nội dung bằng AI, bao gồm gắn thẻ, kiểm duyệt và tạo chú thích
  • Phát hiện và nhận dạng đối tượng bằng nhiều mô hình AI
  • Phân tích chất lượng hình ảnh và phát hiện hình mờ
  • Kiểm duyệt nội dung và phân tích mức độ an toàn
  • Khả năng phát hiện thời trang, văn bản và giải phẫu
  • Phát hiện logo và phân loại sản phẩm (mua sắm)

Máy chủ MediaFlows

  • Xây dựng và quản lý quy trình tự động hóa bằng ngôn ngữ tự nhiên
  • Truy vấn các quy trình tự động hóa PowerFlow hiện có trong môi trường của bạn
  • Tạo logic điều kiện dựa trên siêu dữ liệu, thẻ và thuộc tính tài sản
  • Tự động hóa quy trình kiểm duyệt, phê duyệt và thông báo về tài sản
  • Gỡ lỗi và tìm hiểu cấu hình tự động hóa hiện có

Cần truy cập thêm công cụ Cloudinary?

Chúng tôi đang tiếp tục bổ sung thêm chức năng cho các máy chủ MCP này. Nếu bạn muốn gửi phản hồi, báo lỗi hoặc đề xuất tính năng, vui lòng mở một issue trong kho lưu trữ này.

Khắc phục sự cố

"Claude's response was interrupted..."

Nếu thấy thông báo này, có thể Claude đã chạm đến giới hạn độ dài ngữ cảnh và dừng giữa chừng. Điều này thường xảy ra nhất trên các máy chủ kích hoạt nhiều lệnh gọi công cụ nối tiếp, chẳng hạn như máy chủ quản lý tài sản khi liệt kê số lượng lớn tài sản.

Để giảm khả năng gặp phải vấn đề này:

  • Hãy nêu yêu cầu cụ thể và giữ truy vấn ngắn gọn.
  • Nếu một yêu cầu gọi nhiều công cụ, hãy chia thành một số lệnh gọi công cụ nhỏ hơn để giữ câu trả lời ngắn.
  • Dùng tham số lọc để giới hạn phạm vi tìm kiếm và liệt kê tài sản.

Sự cố xác thực

Đảm bảo thông tin xác thực Cloudinary được cấu hình chính xác và có đủ quyền cần thiết cho các thao tác bạn muốn thực hiện.

Tính năng trả phí

Một số tính năng có thể yêu cầu gói Cloudinary trả phí. Hãy đảm bảo tài khoản Cloudinary của bạn có cấp đăng ký cần thiết cho các tính năng dự định sử dụng, chẳng hạn như:

  • Tính năng phân tích AI nâng cao
  • Mức sử dụng API cao
  • Khả năng biến đổi nâng cao

Giấy phép

Được cấp phép theo MIT License. Xem tệp LICENSE để biết chi tiết.