Cloudinary

官方

使用自然語言與 Cloudinary 的媒體管理平台互動。

GitHub
10
試用此 MCP贊助

你可以用 Cloudinary MCP 做什麼？

  • 上傳與管理媒體資產 — 請您的助理上傳圖片、影片或原始檔案，並透過 Asset Management 伺服器使用資料夾、標籤和關聯來整理這些資產。
  • 轉換與產生資產 — 要求即時的圖片和影片轉換，或為選定的媒體產生壓縮檔與下載連結。
  • 設定環境配置 — 使用 Environment Config 伺服器來設定上傳預設值、轉換預設值、串流設定檔和 Webhook 通知。
  • 建立結構化中繼資料欄位 — 定義具有條件規則和驗證的自訂中繼資料欄位，以提升資產的可搜尋性與組織性。
  • 執行 AI 驅動的內容分析 — 利用 Analysis 伺服器進行自動標籤、內容審核、字幕生成、物體偵測和影像品質評估。
  • 建置工作流程自動化 — 使用 MediaFlows 以自然語言建立和管理低程式碼自動化管線，包括條件邏輯和核准工作流程。

託管 MCP 伺服器

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

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

Cloudinary MCP 伺服器

模型上下文協定（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

目錄

文件

如需使用 Cloudinary 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 端點也接受 POST 請求，作為 /mcp 的別名，因此將 Streamable HTTP 傳送至 /sse 的用戶端也能正常運作。新的設定請使用 /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 伺服器執行

若要使用 Server-Sent Events (SSE) 傳輸方式（而非 stdio）執行本機 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 憑證。

各伺服器功能

資產管理伺服器

  • 上傳及管理媒體資產（圖片、影片、原始檔案）
  • 使用進階篩選功能搜尋及組織資產
  • 處理資產操作與轉換
  • 管理資料夾、標籤及資產關聯
  • 產生封存檔與下載連結

環境設定伺服器

  • 設定上傳預設集與轉換設定
  • 管理串流設定檔與 Webhook 通知
  • 設定上傳對應

結構化中繼資料伺服器

  • 建立及管理結構化中繼資料欄位
  • 設定條件式中繼資料規則與驗證
  • 組織及搜尋中繼資料設定
  • 處理中繼資料欄位關聯與排序

分析伺服器

  • AI 驅動的內容分析，包括標籤、審核及字幕
  • 使用多種 AI 模型進行物件偵測與辨識
  • 影像品質分析與浮水印偵測
  • 內容審核與安全分析
  • 時尚、文字及解剖偵測功能

MediaFlows 伺服器

  • 使用自然語言建構及管理工作流程自動化
  • 查詢您環境中現有的 PowerFlow 自動化
  • 根據中繼資料、標籤及資產屬性建立條件邏輯
  • 自動化資產審核、核准及通知工作流程
  • 除錯及了解現有的自動化設定

需要存取更多 Cloudinary 工具嗎？

我們持續為這些 MCP 伺服器新增更多功能。若您想提供意見回饋、回報錯誤或提出功能請求，請在此儲存庫中開啟 issue。

疑難排解

「Claude 的回應已中斷...」

若您看到此訊息，表示 Claude 可能已達到其上下文長度限制並在回覆中途停止。這最常發生在觸發多個鏈式工具呼叫的伺服器上，例如具有大量資產清單的資產管理伺服器。

為降低遇到此問題的機率：

  • 盡量具體明確，保持查詢簡潔。
  • 若單一請求會呼叫多個工具，請嘗試將其拆分為數個較小的工具呼叫，以保持回應簡短。
  • 使用篩選參數限制資產搜尋與清單的範圍。

驗證問題

請確保您的 Cloudinary 憑證設定正確，並具備執行所需操作的必要權限。

付費功能

某些功能可能需要付費的 Cloudinary 方案。請確保您的 Cloudinary 帳戶具備您欲使用功能所需的訂閱等級，例如：

  • 進階 AI 分析功能
  • 高容量 API 使用
  • 進階轉換功能

授權

依 MIT 授權條款授權。詳細資訊請參閱 LICENSE 檔案。