Cloudinary Asset Management

Cloudinary Asset Management MCP Server

概要

目录

• Cloudinary Asset Management MCP Server
  • 安装
  • 配置
  • 身份验证
  • 可用工具
  • 自定义工具
  • 渐进式发现
• 开发
  • 从源代码构建
  • 贡献

安装

MCP 服务需要 Node.js 20 或更高版本。

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

claude mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

gemini mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

npx @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

npx @cloudinary/asset-management-mcp --help

配置

环境变量

MCP 服务支持以下环境变量：

CLOUDINARY_URL 格式

您可以使用单个 CLOUDINARY_URL，而不必单独设置变量：

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

响应标头收集

您可以将服务器配置为在工具输出中包含 Cloudinary API 响应标头（例如 x-request-id 和速率限制信息）。这有助于调试和监控。

设置 CLOUDINARY_COLLECT_HEADERS，以控制要收集的标头：

# Collect all response headers
CLOUDINARY_COLLECT_HEADERS=true

# Collect specific headers by exact name (comma-separated)
CLOUDINARY_COLLECT_HEADERS=x-request-id,x-featureratelimit-limit,x-featureratelimit-remaining

# Mix exact names, prefix matching, and regex matching
CLOUDINARY_COLLECT_HEADERS=x-request-id,prefix:x-featureratelimit-

标头匹配规范

逗号分隔列表中的每个条目都会与响应标头名称进行匹配：

您也可以通过 CLOUDINARY_URL 查询参数设置此项：

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME?collect_headers=true

启用后，收集的标头会显示在工具响应的 _headers 字段中。未设置时，不会收集任何标头，响应保持不变。

MCP Apps

服务器可以提供交互式 MCP UI 应用（与 io.modelcontextprotocol/ui 规范对齐），供宿主与工具结果一同呈现，例如列表结果的资源库、单个资源的详情视图，以及上传界面。

默认情况下，应用处于启用状态。使用 --mcp-apps 标志（start 和 serve 均可用）或 CLOUDINARY_MCP_APPS 环境变量可覆盖此行为：

可用的应用名称：asset-gallery、asset-details、asset-upload。

# Disable all apps
npx @cloudinary/asset-management-mcp serve --mcp-apps none

# Enable only the gallery
npx @cloudinary/asset-management-mcp start --mcp-apps asset-gallery

# Disable via env var
CLOUDINARY_MCP_APPS=none npx @cloudinary/asset-management-mcp start

优先级：CLI 标志 > 环境变量 > 内置默认值。

身份验证

MCP 服务使用您的 Cloudinary API 密钥和密钥进行身份验证：

{
  "env": {
    "CLOUDINARY_CLOUD_NAME": "demo",
    "CLOUDINARY_API_KEY": "123456789012345",
    "CLOUDINARY_API_SECRET": "abcdefghijklmnopqrstuvwxyz12"
  }
}

可用工具

MCP 服务将 Cloudinary 的 Asset Management API 作为工具提供。使用您的 AI 应用发现并调用可用工具，以上传、管理、搜索和转换媒体资源。

使用示例

示例 1：上传并转换图像

1. Upload a local image: "Upload file:///Users/me/photo.jpg to Cloudinary as 'hero-image'"
2. Transform it: "Transform asset 'hero-image' with transformations 'c_fill,w_800,h_600/e_sharpen'"
3. Get details: "Show me details for asset with ID [asset-id]"

示例 2：搜索和整理资源

1. Search for images: "Find all images with tag 'product' uploaded in the last 7 days"
2. Create folder: "Create a new folder called 'summer-2024-products'"
3. List assets: "Show me all video assets in the 'marketing' folder"

示例 3：生成归档文件

1. Get transformation docs: "Show me the Cloudinary transformation reference"
2. Apply transformations: "Transform 'banner' asset with 'c_scale,w_1200/f_auto,q_auto'"
3. Create archive: "Generate a ZIP archive of all images with tag 'export-ready'"

示例 4：资源管理工作流

1. Upload multiple files: "Upload all images from folder /assets/new-products/"
2. Add tags: "Update asset [asset-id] and add tags 'featured,homepage'"
3. Get usage stats: "Show my Cloudinary account usage statistics"

自定义工具

此 MCP 服务包含两个强大的自定义工具：

get-tx-reference

获取完整的 Cloudinary 转换参考文档。

使用场景：

• 创建或修改转换之前
• 用户询问图像/视频效果、调整大小、裁剪或滤镜时

示例：

Use get-tx-reference to learn about available transformations

transform-asset

使用 Cloudinary 的显式 API 对现有资源应用转换。

参数：

• publicId - 资源的公开 ID
• transformations - 转换字符串（例如，c_fill,w_300,h_200）
• resourceType - 类型：image、video 或 raw（默认值：image）
• invalidate - 使 CDN 缓存失效（默认值：false）

示例：

Transform asset "sample" with transformations "c_fill,w_500,h_500/e_sepia"

渐进式发现

包含大量工具的 MCP 服务可能会占满大模型的上下文窗口，导致 Token 用量增加，并使工具选择变得混乱。动态模式通过仅公开一小组元工具，让 Agent 按需逐步发现并调用工具，从而解决这一问题。

要启用动态模式，请在启动服务时传入 --mode dynamic 标志：

{
  "mcpServers": {
    "CloudinaryAssetMgmt": {
      "command": "npx",
      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic"],
      // ... other server arguments
    }
  }
}

在动态模式下，服务只会注册以下元工具，而不是注册每个独立工具：

• list_tools：列出所有可用工具及其名称和描述。
• describe_tool_input：按名称返回一个或多个工具的输入架构。
• execute_tool：根据名称及其参数执行工具。
• list_scopes：列出服务上可用的范围。

这种方式可大幅减少每次请求发送给大模型的 Token 数量，尤其适用于工具数量较多的服务。

你可以将动态模式与范围和工具筛选器结合使用：

{
  "mcpServers": {
    "CloudinaryAssetMgmt": {
      "command": "npx",
      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic", "--scope", "admin"],
      // ... other server arguments
    }
  }
}

开发

从源代码构建

先决条件

• Node.js v20 或更高版本
• npm、pnpm、bun 或 yarn

构建步骤

# Clone the repository
git clone https://github.com/cloudinary/asset-management-mcp.git
cd asset-management-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

项目结构

asset-management-mcp/
├── src/
│   ├── hooks/              # SDK hooks (manual)
│   │   ├── cloudinaryAuthHook.ts   # Auth & file:// handling
│   │   ├── customHeadersHook.ts    # Inject custom request headers
│   │   ├── responseHeadersHook.ts  # Collect response headers
│   │   ├── userAgentHook.ts        # Build User-Agent string
│   │   └── registration.ts         # Hook registration
│   ├── mcp-server/         # MCP server implementation
│   │   ├── server.ts             # Main server (auto-generated)
│   │   ├── server.extensions.ts  # Custom tools & app wiring (manual)
│   │   ├── tools/                # Generated tool wrappers
│   │   └── apps/                 # MCP UI Apps (manual)
│   │       ├── config.ts             # App registry & --mcp-apps parsing
│   │       ├── cli-flag.ts           # stricli flag definition
│   │       ├── extensions.ts         # Resource-template registration
│   │       ├── uri.ts                # App URI helpers / tool-name injection
│   │       ├── tool-hooks.ts         # Per-tool app hooks
│   │       ├── app-shared.ts         # Shared app utilities
│   │       ├── asset-gallery-app.ts  # List results gallery UI
│   │       ├── asset-details-app.ts  # Single-asset detail UI
│   │       └── asset-upload-app.ts   # Upload UI
│   ├── funcs/              # API function implementations
│   └── models/             # Type definitions
├── .github/
│   └── workflows/          # CI/CD workflows
└── .speakeasy/             # Speakeasy configuration

贡献

我们欢迎为此 MCP 服务贡献代码，但大部分代码都是根据 Cloudinary API 规范通过程序生成的。对生成文件所做的任何手动更改都会在下次生成时被覆盖——请在以下手动扩展点中进行修改。

你可以贡献的内容：

• 在 src/mcp-server/server.extensions.ts 中添加自定义工具和服务配置
• 在 src/mcp-server/apps/ 中开发 MCP UI 应用（图库、详情、上传及新应用）
• 在 src/hooks/ 中添加 SDK 钩子（身份验证、自定义标头、响应标头、用户代理）
• 改进文档（此 README、手动维护文件中的 JSDoc）
• 提交 Bug 报告和功能请求

生成的文件（请勿编辑）：

• src/mcp-server/server.ts
• src/mcp-server/tools/*.ts
• src/funcs/*.ts
• src/models/*.ts

如果无法避免修改生成文件，请优先更新上游规范或 .speakeasy/ 中的 Speakeasy 配置，以确保更改在重新生成后仍然保留。

我们期待听到你的反馈。欢迎提交包含概念验证的 PR 或 issue，我们会尽力将其纳入未来版本。

MCP 服务由 Speakeasy 创建