Cloudinary Asset Management

Cloudinary Asset Management MCP Server

概要

目次

• Cloudinary Asset Management MCP サーバー
  • インストール
  • 設定
  • 認証
  • 利用可能なツール
  • カスタムツール
  • 段階的な検出
• 開発
  • ソースからのビルド
  • コントリビューション

インストール

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 Apps（io.modelcontextprotocol/ui 仕様に準拠）を公開できます。たとえば、リスト結果のアセットギャラリー、単一アセットの詳細ビュー、アップロード UI などがあります。

Apps はデフォルトで有効です。--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 サーバーには、強力なカスタムツールが 2 つ含まれています。

get-tx-reference

Cloudinary の変換に関するリファレンスドキュメント全体を取得します。

使用するタイミング：

• 変換を作成または変更する前
• ユーザーが画像や動画のエフェクト、サイズ変更、クロップ、フィルターについて質問したとき

例：

Use get-tx-reference to learn about available transformations

transform-asset

Cloudinary の explicit 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 サーバーは、LLM のコンテキストウィンドウを肥大化させ、トークン使用量の増加やツールの混乱につながることがあります。ダイナミックモードでは、エージェントが必要に応じてツールを段階的に見つけて呼び出せるように、少数のメタツールのみを公開することでこの問題を解決します。

ダイナミックモードを有効にするには、サーバーの起動時に --mode dynamic フラグを渡します。

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

ダイナミックモードでは、サーバーは個々のツールをすべて登録する代わりに、次のメタツールのみを登録します。

• list_tools：利用可能なすべてのツールの名前と説明を一覧表示します。
• describe_tool_input：名前で指定された 1 つ以上のツールの入力スキーマを返します。
• execute_tool：引数を指定して、名前で指定されたツールを実行します。
• list_scopes：サーバーで利用可能なスコープを一覧表示します。

この方法により、リクエストごとに LLM に送信されるトークン数を大幅に削減できます。ツール数の多いサーバーでは特に便利です。

ダイナミックモードは、スコープやツールのフィルターと組み合わせて使用できます。

{
  "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）
• バグ報告と機能リクエスト

生成ファイル（編集しないでください）：

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

生成ファイルの変更が避けられない場合は、再生成後も変更が保持されるよう、上流の仕様または .speakeasy/ の Speakeasy 設定を更新してください。

皆様からのフィードバックをお待ちしています。概念実証を添えて PR または issue をお気軽にお送りください。今後のリリースに含められるよう、最善を尽くします。

Speakeasy が作成した MCP サーバー