Cloudinary

官方

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

你可以用 Cloudinary MCP 做什麼？

上傳及管理媒體 — 上傳圖片、影片和原始檔案，然後使用資料夾、標籤和資產關聯來整理。
搜尋及轉換資產 — 使用進階篩選條件搜尋資產，並套用資產操作和轉換。
使用 AI 產生圖片 — 根據文字提示或參考圖片建立新圖片，並儲存至您的帳戶。
分析媒體內容 — 對資產執行 AI 標記、審核、加上說明文字、物件偵測，以及浮水印或品質分析。
設定環境設定 — 建立命名轉換、上傳預設集、串流設定檔和 webhook 觸發條件。
管理結構化中繼資料 — 建立中繼資料欄位、設定驗證規則，並管理清單類型欄位的資料來源值。

託管 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 端點也接受 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", "--", "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 伺服器執行

若要使用 Streamable HTTP 傳輸而非 stdio 執行本機 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 Console Dashboard 的 Settings > Security 中找到 Cloudinary 憑證。

各伺服器功能

資產管理伺服器

上傳及管理媒體資產（圖片、影片、原始檔案）
使用進階篩選和視覺搜尋功能搜尋及整理資產
透過文字提示或參考圖片使用 AI 生成新圖片，並直接儲存至您的帳戶
處理資產操作與轉換
管理資料夾、標籤及資產關聯
生成封存檔和下載連結

環境設定伺服器

建立及管理命名轉換和上傳預設集
管理串流設定檔和觸發條件（Webhook 通知）
設定上傳對應

結構化中繼資料伺服器

建立及管理結構化中繼資料欄位
設定條件式中繼資料規則和驗證
管理清單類型中繼資料欄位的資料來源值
整理及搜尋中繼資料設定

分析伺服器

AI 驅動的內容分析，包括標記、審核和加上說明文字
使用多種 AI 模型進行物件偵測與辨識
圖片品質分析和浮水印偵測
內容審核與安全性分析
時尚、文字和人體解剖偵測功能
標誌偵測和產品（商店）分類

MediaFlows 伺服器

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

需要使用更多 Cloudinary 工具嗎？

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

疑難排解

「Claude 的回應遭到中斷……」

如果您看到此訊息，Claude 可能已達到上下文長度限制，因此在回覆中途停止。這種情況最常發生在會觸發多個串連工具呼叫的伺服器上，例如資產管理伺服器列出大量資產時。

若要降低遇到此問題的機率：

請盡量明確，並保持查詢簡潔。
如果單一請求會呼叫多個工具，請嘗試拆分成數個較小的工具呼叫，讓回應保持精簡。
使用篩選參數限制資產搜尋和清單的範圍。

驗證問題

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

付費功能

部分功能可能需要付費的 Cloudinary 方案。請確認您的 Cloudinary 帳戶訂閱等級符合您預計使用的功能需求，例如：

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

授權

採用 MIT License 授權。詳情請參閱 LICENSE 檔案。