# @cloudinary/asset-management-mcp 中文文档

规范地址：https://npmcn.com/package/%40cloudinary/asset-management-mcp/

版本：0\.11\.6
npm 元数据更新时间：2026-11-05T11:22:20.266Z
中文译文更新时间：2026-11-10T04:03:05.699Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudinary/asset-management-mcp
原文对照：https://npmcn.com/package/%40cloudinary/asset-management-mcp/?lang=original
项目主页：https://github.com/cloudinary/asset-management-mcp#readme
源码仓库：https://github.com/cloudinary/asset-management-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：14.5 MB，2276 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.19\.0
- 运行依赖：7 个
- 首次发布：2025-11-18T13:31:38.282Z
- 最新版本发布：2026-11-05T11:22:20.055Z
- 近 30 天下载量：2759（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @cloudinary/asset-management-mcp
```

也可以使用：`pnpm add @cloudinary/asset-management-mcp`、`yarn add @cloudinary/asset-management-mcp`、`bun add @cloudinary/asset-management-mcp`

## README

# 云化资产管理 MCP 服务器

## 内容提要

## 目录

-   [云化资产管理 MCP 服务器](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-cloudinary-asset-management-mcp-server)
    -   [安装](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-installation)
    -   [配置](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-configuration)
    -   [认证](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-authentication)
    -   [可用工具](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-available-tools)
    -   [自定义工具](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-custom-tools)
    -   [进步发现](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-progressive-discovery)
-   [发展](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-development)
    -   [来源建筑](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-building-from-source)
    -   [捐款](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-contributions)

## 安装

MCP服务器需要Node.js 20.19.0或更晚.

克劳德桌面

使用预建的 MCP 服务器安装为桌面扩展 [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.11.6/mcp-server.mcpb) 文件 :

仅仅拖放 [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.11.6/mcp-server.mcpb) 上到 Claude 桌面以安装扩展名.

MCP捆包包括MCP服务器和所有必要配置. 一旦安装完毕,服务器将无需额外设置即可使用.

> \[注\] MCP捆绑为包装和分发MCP服务器提供了简化的方法. 学习更多关于 [桌面扩展](https://www.anthropic.com/engineering/desktop-extensions)。 。 。 .

光标

![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)

或手动:

1.  打开光标设置
2.  选择工具和集成
3.  选择新的 MCP 服务器
4.  如果配置文件为空将以下 JSON 粘贴到 MCP 服务器配置中 :

```json
{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}
```
Claude 代码 CLI

```bash
claude mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 
``` 
双子座

```bash
gemini mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 
``` 
风起浪起

参见 [Windsurf 官方文档](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin) 供参考

1.  打开 Windsurf 设置
2.  在左侧菜单上选择连带
3.  点击 `Manage MCPs`. (管理 MCP 时, 您应该与 Windsurf 账户签名)
4.  点击 `View raw config` 打开 mcp 配置文件.
5.  如果配置文件是空的, 请粘贴完整的 json

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

![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20CloudinaryAssetMgmt%20MCP&color=0098FF)

或手动:

参见 [官方 VS 代码文档](https://code.visualstudio.com/api/extension-guides/ai/mcp) 供参考

1.  打开 [命令调色板](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
2.  搜索和打开 `MCP: Open User Configuration`打开 mcp.json 文件
3.  如果配置文件是空的, 请粘贴完整的 json

```bash
{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}
```
通过 npm 安装 Stdio 要启动 MCP 服务器, 请运行 :

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

服务器参数完整列表中, 运行 :

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

## 配置

### 环境变量

MCP服务器支持以下环境变量:

| 变量 | 说明 | 需求 |
| --- | --- | --- |
| `CLOUDINARY_CLOUD_NAME` | 您的云云名称 | 对 |
| `CLOUDINARY_API_KEY` | 您的云形 API 密钥 | 对 |
| `CLOUDINARY_API_SECRET` | 你的云层API秘密 | 对 |
| `CLOUDINARY_URL` | 完整的云层 URL( 个人 vars 的替代) | 没有 |
| `CLOUDINARY_COLLECT_HEADERS` | 收集 API 响应头(见下文) | 没有 |
| `CLOUDINARY_MCP_APPS` | 覆盖 MCP Apps 默认(参见 [MCP 应用程序](https://npmcn.com/package/%40cloudinary/asset-management-mcp/#readme-mcp-apps)(中文(简体) ) | 没有 |

### 克洛迪纳里-乌尔尔 格式

你可以用单曲 `CLOUDINARY_URL` 而不是单个变量 :

```bash
CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
```

### 回复信头收藏

您可以配置服务器以包含 Cloudinary API 响应头( 例如) `x-request-id` 和速度限制信息)在工具输出中。 这可用于调试和监测.

设定 `CLOUDINARY_COLLECT_HEADERS` 以控制收集哪些信头:

```bash
# 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-
```

#### 匹配规格的页眉

逗号分隔列表中的每个条目与响应头名称相匹配 :

| 格式 | 示例 | 行为 |
| --- | --- | --- |
| 确切名称 | `x-request-id` | 仅匹配 `x-request-id` |
| `prefix:<value>` | `prefix:x-featureratelimit-` | 匹配任何以 `x-featureratelimit-` |
| `regex:<pattern>` | `regex:ratelimit` | 匹配名称包含的任何标题 `ratelimit` |

也可以通过 `CLOUDINARY_URL` 查询参数 :

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

启用时,所收集的标题出现在 `_headers` 字段在工具响应中。 未设置时,不收集信头,答复不变.

### MCP 应用程序

服务器可以曝光交互式 MCP UI **应用程序** (与 `io.modelcontextprotocol/ui`),主机可以同时提供工具结果——例如列表结果的资产库,单资产细节视图,以及上传UI.

Apps为 **默认启用**。使用 `--mcp-apps` 旗帜(可同时使用) `start` 财务报告和审定财务报表 `serve`)或为: `CLOUDINARY_MCP_APPS` 覆盖此行为的环境变量 :

| 数值 | 效果 |
| --- | --- |
| 未设定 | 默认 —— **所有应用程序已启用** |
| 赤线 `--mcp-apps` (无值), `all`,或 `true` | 启用每个应用程序( 与默认相同) |
| `none` 或者说 `false` | 禁用每个应用程序( kill- switch) |
| 逗号分隔子集,例如:. `asset-gallery,asset-details` | 只启用列出的应用程序 |

可用的应用程序名称 : `asset-gallery`, (中文(简体) ), `asset-details`, (中文(简体) ), `asset-upload`。 。 。 .

```bash
# 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 密钥和密钥进行认证 :

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

## 可用工具

MCP服务器将Cloudinary的资产管理API曝光为工具. 使用您的 AI 应用程序来发现和引用用于上传,管理,搜索和转换您的媒体资产的可用工具.

### 用法实例

#### 示例1: 上传并转换图像

```yaml
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:搜索和组织资产

```yaml
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:生成归档

```yaml
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:资产管理工作流程

```yaml
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`

检索完整的"云变"参考文献.

**何时使用 :**

-   在创建或修改转换之前
-   当用户询问图像/视频效果时, 调整大小、 裁剪、 过滤器

**示例**

```sh
Use get-tx-reference to learn about available transformations
```

### `transform-asset`

使用 Cloudinary 的 API 来应用变换到现有的资产 .

**参数:**

-   `publicId` - 该资产的公共身份
-   `transformations` - 转换字符串(例如, `c_fill,w_300,h_200`(中文(简体) )
-   `resourceType` - 类型 : `image`, (中文(简体) ), `video`,或 `raw` (默认 : `image`(中文(简体) )
-   `invalidate` - 无效的 CDN 缓存( 默认 ): `false`(中文(简体) )

**示例**

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

## 进步发现

拥有许多工具的MCP服务器可以 bloat LLM 上下文窗口,导致符号使用和工具混淆增加. 动态模式解决了这个问题,它只暴露出一组小的元工具,让代理逐渐发现并按需要引用工具.

要启用动态模式,请通过 `--mode dynamic` 启动服务器时的旗帜 :

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

在动态模式下,服务器只登记以下元工具,而不是每个单个工具:

-   **`list_tools`**:列出所有可用的工具及其名称和说明.
-   **`describe_tool_input`**: 以名称返回一个或多个工具的输入方案.
-   **`execute_tool`**: 执行一个工具的名称及其参数.
-   **`list_scopes`**:列出服务器上可用的范围.

这种方法会大大减少每个请求发送到LLM的令牌数量,这对拥有大量工具的服务器特别有用.

您可以将动态模式和范围及工具过滤器结合起来:

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

# 发展

## 来源建筑

### 先决条件

-   节点.js v20 或以上
-   npm, pnpm, bun, 或纱线

### 构建步骤

```bash
# 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
```

### 项目结构

```ini
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`
-   MCP UI 应用程序在 `src/mcp-server/apps/` (垃圾、细节、上传和新应用)
-   SDK 钩入 `src/hooks/` (自动,自定义信头,响应信头,用户代理)
-   文件改进( 手动文件中的 README、 JSDoc)
-   错误报告和特性请求

**生成的文件( 不编辑) :**

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

当触摸生成的文件不可避免时, 更倾向于更新上游光谱或 Speakeeasy 配置 `.speakeasy/` 所以改变能活下来.

我们期待着听到你的反馈。 随便你开个公关 或者用概念证明的问题 我们会尽力把它纳入未来的发行.

* * *

### MCP 服务器创建于 [说话方便](https://www.speakeasy.com/?utm_source=asset-management-mcp&utm_campaign=mcp-typescript)

## 常见问题

### 如何安装 @cloudinary/asset-management-mcp？

在项目目录运行 npm install @cloudinary/asset-management-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp、asset-management-mcp，可以用 npx mcp 直接运行。

### @cloudinary/asset-management-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cloudinary\_\_asset-management-mcp 是否存在。

### @cloudinary/asset-management-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cloudinary/asset-management-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudinary/asset-management-mcp 可以商用吗？

@cloudinary/asset-management-mcp 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudinary/asset-management-mcp 的下载量有多少？

根据 npm 官方下载统计，@cloudinary/asset-management-mcp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,759 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudinary/asset-management-mcp 还在维护吗？

最新版本 0\.11\.6 发布于 2026/11/05（4 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2025/11/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。