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 全套媒体优化和管理功能。

以下 MCP 服务器可用于 Cloudinary：

服务器名称描述远程 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 的别名，因此向 /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 服务器运行

要使用 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 文件。