Cloudinary

官方

使用自然语言与Cloudinary的媒体管理平台进行交互。

你可以用 Cloudinary MCP 做什么？

上传和管理媒体 — 上传图像、视频和原始文件，然后使用文件夹、标签和资源关系进行整理。
搜索和转换资源 — 使用高级筛选条件搜索资源，并对资源应用操作和转换。
使用 AI 生成图像 — 根据文本提示或参考图像创建新图像，并将其保存到您的帐户。
分析媒体内容 — 对资源运行 AI 标签、审核、字幕生成、对象检测以及水印或质量分析。
配置环境设置 — 创建命名转换、上传预设、流媒体配置文件和 Webhook 触发器。
管理结构化元数据 — 创建元数据字段、设置验证规则，并管理列表类型字段的数据源值。

托管 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 服务器
资源管理	上传、管理、搜索和转换媒体资源，并根据文本提示或参考图像使用 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 的别名，因此向 /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", "--", "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 文件。