Cloudinary MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'cloudinarymcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Cloudinary MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'cloudinarymcp_get_tx_reference',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "cloudinarymcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Cloudinary MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="cloudinarymcp_get_tx_reference",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Search visual, folders, assets — Finds images in your asset library based on visual similarity or content

Returns a list of resources that are visually similar to a specified image

• Asset upload, transform — Uploads media assets (images, videos, raw files) to your Cloudinary product environment

Uploads media assets (images, videos, raw files) to your Cloudinary product environment

• Folder move — Renames or moves an entire folder (along with all assets it contains) to a new location

Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library

• List videos, tags, images — Get video assets

Retrieves a list of video assets

• Get usage details, tx reference, asset details — Retrieves comprehensive usage metrics and account statistics

A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage

• Archive generate — Creates an archive (ZIP or TGZ file) that contains a set of assets from your product environment

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

cloudinarymcp_asset_rename#Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account2 params▾

Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account

NameTypeRequiredDescription

RequestBodyobjectrequiredThe rename request parameters.

resource_typestringrequiredThe type of resource (image, video, or raw).

cloudinarymcp_asset_update#Updates an existing asset's metadata, tags, and other attributes using its asset ID Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. Note that you can also update attributes of an existing asset using the explicit API endpoint.2 params▾

Updates an existing asset's metadata, tags, and other attributes using its asset ID Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. Note that you can also update attributes of an existing asset using the explicit API endpoint.

NameTypeRequiredDescription

asset_idstringrequiredThe asset ID of the resource. Must be a 32-character hexadecimal string.

ResourceUpdateRequestobjectrequiredThe asset attributes to update.

cloudinarymcp_create_asset_relations#Add related assets by asset ID Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.2 params▾

Add related assets by asset ID Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.

NameTypeRequiredDescription

asset_idstringrequiredThe asset ID of the resource. Must be a 32-character hexadecimal string.

relate_assets_by_asset_id_requestobjectrequiredThe asset IDs to relate.

cloudinarymcp_create_folder#Creates a new empty folder in your Cloudinary media library Creates a new folder at the specified path1 param▾

Creates a new empty folder in your Cloudinary media library Creates a new folder at the specified path

NameTypeRequiredDescription

folderstringrequiredThe full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

cloudinarymcp_delete_asset#Delete asset by asset ID Deletes an asset using its immutable asset ID.1 param▾

Delete asset by asset ID Deletes an asset using its immutable asset ID.

NameTypeRequiredDescription

requestobjectrequiredThe asset to delete and related options.

cloudinarymcp_delete_asset_relations#Delete asset relations by asset ID Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.2 params▾

Delete asset relations by asset ID Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.

NameTypeRequiredDescription

asset_idstringrequiredThe asset ID of the resource. Must be a 32-character hexadecimal string.

unrelate_assets_by_asset_id_requestobjectrequiredThe asset IDs to unrelate.

cloudinarymcp_delete_derived_assets#Delete derived resources Deletes derived resources by derived resource ID1 param▾

Delete derived resources Deletes derived resources by derived resource ID

NameTypeRequiredDescription

requestobjectrequiredThe derived resource IDs to delete.

cloudinarymcp_delete_folder#Deletes an existing folder from your media library Deletes a folder and all assets within it.1 param▾

Deletes an existing folder from your media library Deletes a folder and all assets within it.

NameTypeRequiredDescription

folderstringrequiredThe full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

cloudinarymcp_download_asset_backup#Download a backup copy of an asset2 params▾

Download a backup copy of an asset

NameTypeRequiredDescription

asset_idstringrequiredThe asset ID of the resource. Must be a 32-character hexadecimal string.

version_idstringrequiredThe version ID of the backup to download. Must be a 32-character hexadecimal string.

cloudinarymcp_generate_archive#Creates an archive (ZIP or TGZ file) that contains a set of assets from your product environment. Creates a downloadable ZIP or other archive format containing the specified resources.2 params▾

Creates an archive (ZIP or TGZ file) that contains a set of assets from your product environment. Creates a downloadable ZIP or other archive format containing the specified resources.

NameTypeRequiredDescription

RequestBodyobjectrequiredThe archive generation parameters.

resource_typestringrequiredThe type of resource for archive generation (image, video, or raw).

cloudinarymcp_get_asset_details#Get resource by asset ID Returns the details of a single resource specified by its asset ID.12 params▾

Get resource by asset ID Returns the details of a single resource specified by its asset ID.

NameTypeRequiredDescription

asset_idstringrequiredThe asset ID of the resource. Must be a 32-character hexadecimal string.

accessibility_analysisbooleanoptionalWhether to return accessibility analysis scores for the image. Default: false.

colorsbooleanoptionalWhether to include color information (predominant colors and histogram of 32 leading colors). Default: false.

coordinatesbooleanoptionalWhether to include previously specified custom cropping coordinates and faces coordinates. Default: false.

derived_next_cursorstringoptionalThe cursor for the next page of derived assets when there are more derived images than max_results.

facesbooleanoptionalWhether to include a list of coordinates of detected faces. Default: false.

max_resultsintegeroptionalMaximum number of derived assets to return. Default: 10.

media_metadatabooleanoptionalWhether to include IPTC, XMP, and detailed Exif metadata in the response. Default: false.

pagesbooleanoptionalWhether to report the number of pages in multi-page documents (e.g., PDF). Default: false.

phashbooleanoptionalWhether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false.

quality_analysisbooleanoptionalWhether to return quality analysis scores for the image. Default: false.

versionsbooleanoptionalWhether to include details of all the backed up versions of the asset. Default: false.

cloudinarymcp_get_tx_reference#Get Cloudinary transformation rules documentation from official docs MANDATORY before creating, modifying, or discussing Cloudinary transformations. Required when user asks for image/video effects, resizing, cropping, filters, etc. Not needed for simple asset management (upload, list, delete, etc.). Call only once per session - documentation doesn't change, reuse the knowledge. This tool returns the complete, authoritative Cloudinary transformation reference that contains all valid parameters, syntax rules, and best practices.0 params▾

Get Cloudinary transformation rules documentation from official docs MANDATORY before creating, modifying, or discussing Cloudinary transformations. Required when user asks for image/video effects, resizing, cropping, filters, etc. Not needed for simple asset management (upload, list, delete, etc.). Call only once per session - documentation doesn't change, reuse the knowledge. This tool returns the complete, authoritative Cloudinary transformation reference that contains all valid parameters, syntax rules, and best practices.

cloudinarymcp_get_usage_details#Retrieves comprehensive usage metrics and account statistics A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage. No date parameter needed to get current usage statistics.1 param▾

Retrieves comprehensive usage metrics and account statistics A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage. No date parameter needed to get current usage statistics.

NameTypeRequiredDescription

datestringoptionalThe date for which to retrieve usage details (YYYY-MM-DD). If not specified, returns the current usage.

cloudinarymcp_list_files#Get raw assets Retrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.9 params▾

Get raw assets Retrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.

NameTypeRequiredDescription

directionstringoptionalThe sort direction for the results. Default is "desc".

fieldsstringoptionalAdditional fields to include in the response. The fields public_id and asset_id are always included.

max_resultsintegeroptionalMaximum number of results to return (1-500).

next_cursorstringoptionalCursor for pagination.

prefixstringoptionalA public_id prefix. When specified, all assets with that prefix are returned.

public_idsarrayoptionalAn array of public IDs to return.

start_atstringoptionalAn ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.

tagsbooleanoptionalWhether to include the list of tag names assigned to each asset. Default is false.

typestringoptionalThe delivery type to filter by. When omitted, returns assets of all delivery types.

cloudinarymcp_list_images#Get image assets Retrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.9 params▾

Get image assets Retrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.

NameTypeRequiredDescription

directionstringoptionalThe sort direction for the results. Default is "desc".

fieldsstringoptionalAdditional fields to include in the response. The fields public_id and asset_id are always included.

max_resultsintegeroptionalMaximum number of results to return (1-500).

next_cursorstringoptionalCursor for pagination.

prefixstringoptionalA public_id prefix. When specified, all assets with that prefix are returned.

public_idsarrayoptionalAn array of public IDs to return.

start_atstringoptionalAn ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.

tagsbooleanoptionalWhether to include the list of tag names assigned to each asset. Default is false.

typestringoptionalThe delivery type to filter by. When omitted, returns assets of all delivery types.

cloudinarymcp_list_tags#Retrieves a list of tags currently applied to assets in your Cloudinary account Retrieves a comprehensive list of all tags that exist in your product environment for assets of the specified type. [Cloudinary Admin API documentation](https://cloudinary.com/documentation/admin_api)4 params▾

Retrieves a list of tags currently applied to assets in your Cloudinary account Retrieves a comprehensive list of all tags that exist in your product environment for assets of the specified type. [Cloudinary Admin API documentation](https://cloudinary.com/documentation/admin_api)

NameTypeRequiredDescription

resource_typestringrequiredThe type of resource (image, video, or raw).

max_resultsintegeroptionalMaximum number of results to return (1-500).

next_cursorstringoptionalCursor for pagination.

prefixstringoptionalLimit the returned tags to those that start with the specified prefix.

cloudinarymcp_list_videos#Get video assets Retrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.9 params▾

Get video assets Retrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.

NameTypeRequiredDescription

directionstringoptionalThe sort direction for the results. Default is "desc".

fieldsstringoptionalAdditional fields to include in the response. The fields public_id and asset_id are always included.

max_resultsintegeroptionalMaximum number of results to return (1-500).

next_cursorstringoptionalCursor for pagination.

prefixstringoptionalA public_id prefix. When specified, all assets with that prefix are returned.

public_idsarrayoptionalAn array of public IDs to return.

start_atstringoptionalAn ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.

tagsbooleanoptionalWhether to include the list of tag names assigned to each asset. Default is false.

typestringoptionalThe delivery type to filter by. When omitted, returns assets of all delivery types.

cloudinarymcp_move_folder#Renames or moves an entire folder (along with all assets it contains) to a new location Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library.2 params▾

Renames or moves an entire folder (along with all assets it contains) to a new location Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library.

NameTypeRequiredDescription

folderstringrequiredThe full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

move_folder_requestobjectrequiredThe new folder path.

cloudinarymcp_search_assets#Provides a powerful query interface to filter and retrieve assets and their details Returns a list of resources matching the specified search criteria. Uses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference.1 param▾

Provides a powerful query interface to filter and retrieve assets and their details Returns a list of resources matching the specified search criteria. Uses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference.

NameTypeRequiredDescription

requestobjectrequiredThe search query parameters.

cloudinarymcp_search_folders#Searches for folders whose attributes match a given expression Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.4 params▾

Searches for folders whose attributes match a given expression Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.

NameTypeRequiredDescription

expressionstringoptionalThe (Lucene-like) string expression specifying the search query. If not passed, returns all folders (up to max_results).

max_resultsintegeroptionalMaximum number of folders to return (max 500, default 50).

next_cursorstringoptionalThe cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.

sort_byarrayoptionalSort order for the results. Each item maps a field name to a direction.

cloudinarymcp_transform_asset#Generate derived transformations for existing assets using Cloudinary's explicit API with eager transformations ⚠️ CRITICAL PREREQUISITES: 1. MUST call get-tx-reference tool first 2. MUST validate transformation syntax against official docs 3. MUST use only documented parameters from the reference 4. MUST follow proper URL component structure (slashes between components, commas within) 📋 VALIDATION CHECKLIST: - ✅ Called get-tx-reference tool - ✅ Verified all parameters exist in official docs - ✅ Used correct syntax (e.g., f_auto/q_auto not f_auto,q_auto) - ✅ Applied proper component chaining rules - ✅ Included crop mode when using width/height This tool creates actual derived assets on Cloudinary using the explicit API.4 params▾

Generate derived transformations for existing assets using Cloudinary's explicit API with eager transformations ⚠️ CRITICAL PREREQUISITES: 1. MUST call get-tx-reference tool first 2. MUST validate transformation syntax against official docs 3. MUST use only documented parameters from the reference 4. MUST follow proper URL component structure (slashes between components, commas within) 📋 VALIDATION CHECKLIST: - ✅ Called get-tx-reference tool - ✅ Verified all parameters exist in official docs - ✅ Used correct syntax (e.g., f_auto/q_auto not f_auto,q_auto) - ✅ Applied proper component chaining rules - ✅ Included crop mode when using width/height This tool creates actual derived assets on Cloudinary using the explicit API.

NameTypeRequiredDescription

publicIdstringrequiredThe public ID of the existing asset to transform

transformationsstringrequiredVALIDATED transformation string using ONLY parameters from get-tx-reference docs. Examples: 'c_fill,w_300,h_200' or 'e_sepia/a_90'. MUST follow component rules: commas within components, slashes between components.

invalidatebooleanoptionalWhether to invalidate cached versions

resourceTypestringoptionalThe resource type of the asset

cloudinarymcp_upload_asset#Uploads media assets (images, videos, raw files) to your Cloudinary product environment Uploads media assets (images, videos, raw files) to your Cloudinary product environment. The file is securely stored in the cloud with backup and revision history. Cloudinary automatically analyzes and saves important data about each asset, such as format, size, resolution, and prominent colors, which is indexed to enable searching on those attributes. Supports uploading from: - Local file paths (SDKs/MCP server only). For MCP server path MUST start with file:// - Remote HTTP/HTTPS URLs - Base64 Data URIs (max ~60 MB) - Private storage buckets (S3 or Google Storage) - FTP addresses The uploaded asset is immediately available for transformation and delivery upon successful upload. Transform media files using transformation syntax in delivery URLs, which creates derived files accessible immediately without re-uploading the original.2 params▾

Uploads media assets (images, videos, raw files) to your Cloudinary product environment Uploads media assets (images, videos, raw files) to your Cloudinary product environment. The file is securely stored in the cloud with backup and revision history. Cloudinary automatically analyzes and saves important data about each asset, such as format, size, resolution, and prominent colors, which is indexed to enable searching on those attributes. Supports uploading from: - Local file paths (SDKs/MCP server only). For MCP server path MUST start with file:// - Remote HTTP/HTTPS URLs - Base64 Data URIs (max ~60 MB) - Private storage buckets (S3 or Google Storage) - FTP addresses The uploaded asset is immediately available for transformation and delivery upon successful upload. Transform media files using transformation syntax in delivery URLs, which creates derived files accessible immediately without re-uploading the original.

NameTypeRequiredDescription

upload_requestobjectrequiredThe file to upload and associated parameters.

resource_typestringoptionalThe type of resource (image, video, raw, or auto).

cloudinarymcp_visual_search_assets#Finds images in your asset library based on visual similarity or content Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways: - Provide a URL of an image - Specify the asset ID of an existing image - Provide a textual description1 param▾

Finds images in your asset library based on visual similarity or content Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways: - Provide a URL of an image - Specify the asset ID of an existing image - Provide a textual description

NameTypeRequiredDescription

requeststringrequiredThe visual search parameters.