The Cloudinary MCP connector routes your AI agent's tool calls to Cloudinary's own MCP server through Scalekit. Each user signs in to Cloudinary once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 30 tools.
- Tools
- 30
- What they doRead · write · destructive
- 12 · 11 · 712 read11 write7 destructive
- Users sign in with
- OAuth
- OAuth app
- Scalekit's or your own
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. 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>Create the Cloudinary MCP connection
In AgentKit > Connections, create a Cloudinary MCP connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Scalekit credentials are available for Cloudinary MCP server, so you don't need to register an OAuth app.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'cloudinarymcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Cloudinary MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'cloudinarymcp_get_tx_reference',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "cloudinarymcp"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="cloudinarymcp_get_tx_reference",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolcloudinarymcp_get_asset_detailsGet resource by asset ID Returns the details of a single resource specified by its asset ID.Read-onlyGet Asset Details
Get resource by asset ID Returns the details of a single resource specified by its asset ID.
Inputs
asset_idstringrequired- The asset ID of the resource. Must be a 32-character hexadecimal string.
accessibility_analysisboolean- Whether to return accessibility analysis scores for the image. Default: false.default
false colorsboolean- Whether to include color information (predominant colors and histogram of 32 leading colors). Default: false.default
false coordinatesboolean- Whether to include previously specified custom cropping coordinates and faces coordinates. Default: false.default
false derived_next_cursorstring- The cursor for the next page of derived assets when there are more derived images than max_results.
facesboolean- Whether to include a list of coordinates of detected faces. Default: false.default
false max_resultsinteger- Maximum number of derived assets to return. Default: 10.default
10 media_metadataboolean- Whether to include IPTC, XMP, and detailed Exif metadata in the response. Default: false.default
false pagesboolean- Whether to report the number of pages in multi-page documents (e.g., PDF). Default: false.default
false phashboolean- Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false.default
false quality_analysisboolean- Whether to return quality analysis scores for the image. Default: false.default
false versionsboolean- Whether to include details of all the backed up versions of the asset. Default: false.default
false
cloudinarymcp_get_generation_taskGet a generation task Get the status of a generation task.Read-onlyGet a Generation Task
Get a generation task Get the status of a generation task.
Inputs
task_idstringrequired- The ID of the generation task.
cloudinarymcp_get_tx_referenceGet Cloudinary transformation rules documentation from official docs MANDATORY before creating, modifying, or discussing Cloudinary transformations.Read-onlyGet 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.
Inputs
This tool takes no inputs.
cloudinarymcp_get_usage_detailsRetrieves 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.Read-onlyGet 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.
Inputs
datestring- The date for which to retrieve usage details (YYYY-MM-DD). If not specified, returns the current usage.
cloudinarymcp_list_filesGet raw assets Retrieves a list of raw assets.Read-onlyList Files
Get raw assets Retrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
Inputs
directionstring- The sort direction for the results. Default is "desc".one of
ascdesc fieldsstring- Additional fields to include in the response. The fields public_id and asset_id are always included.
max_resultsinteger- Maximum number of results to return (1-500).
next_cursorstring- Cursor for pagination.
prefixstring- A public_id prefix. When specified, all assets with that prefix are returned.
public_idsarray- An array of public IDs to return.
start_atstring- An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.
tagsboolean- Whether to include the list of tag names assigned to each asset. Default is false.default
false typestring- The delivery type to filter by. When omitted, returns assets of all delivery types.
cloudinarymcp_list_imagesGet image assets Retrieves a list of image assets.Read-onlyList Images
Get image assets Retrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
Inputs
directionstring- The sort direction for the results. Default is "desc".one of
ascdesc fieldsstring- Additional fields to include in the response. The fields public_id and asset_id are always included.
max_resultsinteger- Maximum number of results to return (1-500).
next_cursorstring- Cursor for pagination.
prefixstring- A public_id prefix. When specified, all assets with that prefix are returned.
public_idsarray- An array of public IDs to return.
start_atstring- An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.
tagsboolean- Whether to include the list of tag names assigned to each asset. Default is false.default
false typestring- The delivery type to filter by. When omitted, returns assets of all delivery types.
cloudinarymcp_list_videosGet video assets Retrieves a list of video assets.Read-onlyList Videos
Get video assets Retrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
Inputs
directionstring- The sort direction for the results. Default is "desc".one of
ascdesc fieldsstring- Additional fields to include in the response. The fields public_id and asset_id are always included.
max_resultsinteger- Maximum number of results to return (1-500).
next_cursorstring- Cursor for pagination.
prefixstring- A public_id prefix. When specified, all assets with that prefix are returned.
public_idsarray- An array of public IDs to return.
start_atstring- An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.
tagsboolean- Whether to include the list of tag names assigned to each asset. Default is false.default
false typestring- The delivery type to filter by. When omitted, returns assets of all delivery types.
cloudinarymcp_search_assetsProvides a powerful query interface to filter and retrieve assets and their details Returns a list of resources matching the specified search criteria.Read-onlySearch 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.
Inputs
requestobjectrequired- The search query parameters.
cloudinarymcp_search_foldersSearches for folders whose attributes match a given expression Lists the folders that match the specified search expression.Read-onlySearch 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.
Inputs
expressionstring- The (Lucene-like) string expression specifying the search query. If not passed, returns all folders (up to max_results).
max_resultsinteger- Maximum number of folders to return (max 500, default 50).default
50 next_cursorstring- The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.
sort_byarray- Sort order for the results. Each item maps a field name to a direction.
cloudinarymcp_sign_uploadUse this tool when the user wants to upload a file to Cloudinary directly from their own machine or environment.Read-onlySign Upload
Use this tool when the user wants to upload a file to Cloudinary directly from their own machine or environment. It signs Upload API parameters so the caller can POST files straight to the Cloudinary Upload API — no API secret required on the client side. NOT suitable for large files (>100 MB) or bulk uploads — direct the user to the Cloudinary CLI (`cld uploader upload`) or an SDK instead, which handle chunking, retries, and progress reporting. Returns one credential object per input entry: upload_params — serialized params to echo verbatim as form fields (includes timestamp) api_key — Cloudinary API key signature — HMAC signature over upload_params; invalidated if any field is changed host — Upload API hostname (may differ from api.cloudinary.com for regional/enterprise accounts) cloud_name — Cloudinary cloud name Send only signable params in the input (public_id, folder, tags, context, metadata, eager, transformation, …). Do not include file, resource_type, api_key, or signature — these are not part of the signed parameter set and will be ignored if passed. To upload after signing, POST multipart/form-data to: https://<host>/v1_1/<cloud_name>/<resource_type>/upload Include your file plus api_key, signature, and EVERY key from upload_params as its own form field. Any added, dropped, renamed, or re-serialized field invalidates the signature. resource_type (image/video/raw/auto) is part of the URL, not upload_params. Example (all upload_params keys must appear — shown here with public_id and timestamp only for brevity; include every key your upload_params actually contains): curl https://<host>/v1_1/<cloud_name>/image/upload \ -F 'file=@"/path/to/photo.jpg"' \ -F 'api_key=<api_key>' -F 'signature=<signature>' \ -F 'timestamp=<upload_params.timestamp>' \ -F 'public_id=<upload_params.public_id>' # one -F per upload_params key IMPORTANT — the file= argument MUST use two quoting layers: single-quotes around the entire -F value (shell), double-quotes around the path (curl): -F 'file=@"<path>"'. Paths with spaces or special characters are common and will be word-split by the shell if unquoted, silently truncating the filename at the first space.
Inputs
uploadsarrayrequired- One or more sets of Cloudinary Upload API parameters to sign. Returns one signed credential object per entry, in the same order. Only genuine Upload API params are signed; file, resource_type, api_key, and signature are excluded.
cloudinarymcp_visual_search_assetsFinds images in your asset library based on visual similarity or content Returns a list of resources that are visually similar to a specified image.Read-onlyVisual 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 description
Inputs
requeststringrequired- The visual search parameters.
cloudinarymcp_asset_renameUpdates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary accountWriteAsset Rename
Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account
- Idempotent
Inputs
RequestBodyobjectrequired- The rename request parameters.
resource_typestringrequired- The type of resource (image, video, or raw).one of
imagevideoraw
cloudinarymcp_asset_updateUpdates 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.WriteAsset 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.
- Idempotent
Inputs
asset_idstringrequired- The asset ID of the resource. Must be a 32-character hexadecimal string.
ResourceUpdateRequestobjectrequired- The asset attributes to update.
cloudinarymcp_create_asset_relationsAdd 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.WriteCreate 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.
Inputs
asset_idstringrequired- The asset ID of the resource. Must be a 32-character hexadecimal string.
relate_assets_by_asset_id_requestobjectrequired- The asset IDs to relate.
cloudinarymcp_create_folderCreates a new empty folder in your Cloudinary media library Creates a new folder at the specified pathWriteCreate Folder
Creates a new empty folder in your Cloudinary media library Creates a new folder at the specified path
Inputs
folderstringrequired- The 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_backupDownload a backup copy of an assetWriteDownload Asset Backup
Download a backup copy of an asset
- Idempotent
Inputs
asset_idstringrequired- The asset ID of the resource. Must be a 32-character hexadecimal string.
version_idstringrequired- The version ID of the backup to download. Must be a 32-character hexadecimal string.
cloudinarymcp_generate_archiveCreates an archive (ZIP or TGZ file) that contains a set of assets from your product environment.WriteGenerate 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.
- Idempotent
Inputs
RequestBodyobjectrequired- The archive generation parameters.
resource_typestringrequired- The type of resource for archive generation (image, video, or raw).one of
imagevideorawall
cloudinarymcp_generate_imageGenerate an image Generate an image from a text prompt using AI models.WriteGenerate an Image
Generate an image Generate an image from a text prompt using AI models. The model is selected via the optional `model` object: 1. If `model.id` is provided, use that exact model. 2. Else if `model.family` (+ optional `model.tier`) is provided, resolve via the model registry; a missing tier defaults to `standard`. 3. If `model` is omitted, use the global default (nano-banana / premium, i.e. `nano-banana-2`).
Inputs
requestobjectrequired- A JSON object containing the generation request parameters.
cloudinarymcp_generate_image_from_imagesGenerate an image from reference images Generate an image guided by one or more **reference images** — restyle, on-brand variants, character consistency, virtual try-on, edit/extend — steered by `prompt`.WriteGenerate an Image from Reference Images
Generate an image from reference images Generate an image guided by one or more **reference images** — restyle, on-brand variants, character consistency, virtual try-on, edit/extend — steered by `prompt`. Only edit-capable models are selectable here. The model is selected via the optional `model` object, exactly like `text_to_image`, but IDs are restricted to edit models: 1. If `model.id` is provided, use that exact edit model. 2. Else if `model.family` (+ optional `model.tier`) is provided, resolve to that family's edit model (e.g. `nano-banana` / `premium` → `nano-banana-2-edit`). 3. If `model` is omitted, use the default edit model (`nano-banana-2-edit`). Each reference image is either a stored managed asset (by `asset_id`, read-permission checked) or an external HTTPS `url`.
Inputs
requestobjectrequired- A JSON object containing the image-to-image generation request parameters.
cloudinarymcp_move_folderRenames 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.WriteMove 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.
- Idempotent
Inputs
folderstringrequired- The 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_requestobjectrequired- The new folder path.
cloudinarymcp_transform_assetGenerate derived transformations for existing assets using Cloudinary's explicit API with eager transformations ⚠️ CRITICAL PREREQUISITES: 1.WriteTransform 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.
- Idempotent
Inputs
publicIdstringrequired- The public ID of the existing asset to transform
transformationsstringrequired- VALIDATED 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.
invalidateboolean- Whether to invalidate cached versionsdefault
false resourceTypestring- The resource type of the assetone of
imagevideorawdefaultimage
cloudinarymcp_upload_assetUploads media assets (images, videos, raw files) to your Cloudinary product environment Uploads media assets (images, videos, raw files) to your Cloudinary product environment.WriteUpload 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.
Inputs
upload_requestobjectrequired- The file to upload and associated parameters.
resource_typestring- The type of resource (image, video, raw, or auto).one of
imagevideorawautodefaultauto
cloudinarymcp_delete_assetDelete asset by asset ID Deletes an asset using its immutable asset ID.DestructiveDelete Asset
Delete asset by asset ID Deletes an asset using its immutable asset ID.
Inputs
requestobjectrequired- The asset to delete and related options.
cloudinarymcp_delete_asset_relationsDelete 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.DestructiveDelete 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.
Inputs
asset_idstringrequired- The asset ID of the resource. Must be a 32-character hexadecimal string.
unrelate_assets_by_asset_id_requestobjectrequired- The asset IDs to unrelate.
cloudinarymcp_delete_derived_assetsDelete derived resources Deletes derived resources by derived resource IDDestructiveDelete Derived Assets
Delete derived resources Deletes derived resources by derived resource ID
Inputs
requestobjectrequired- The derived resource IDs to delete.
cloudinarymcp_delete_folderDeletes an existing folder from your media library Deletes a folder and all assets within it.DestructiveDelete Folder
Deletes an existing folder from your media library Deletes a folder and all assets within it.
Inputs
folderstringrequired- The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.
cloudinarymcp_manage_asset_contextAdds or clears contextual metadata on multiple assets Applies a contextual-metadata command to the given assets, addressing them by public ID.DestructiveManage Asset Contextual Metadata
Adds or clears contextual metadata on multiple assets Applies a contextual-metadata command to the given assets, addressing them by public ID.
Inputs
context_update_requestobjectrequired- The context command, the metadata to apply, and the assets to apply it to.
resource_typestringrequired- The type of resource (image, video, or raw).one of
imagevideoraw
cloudinarymcp_manage_asset_metadataSets structured metadata values on multiple assets Assigns structured metadata field values to the given assets, addressing them by public ID.DestructiveManage Asset Structured Metadata
Sets structured metadata values on multiple assets Assigns structured metadata field values to the given assets, addressing them by public ID. Values are merged into each asset's existing structured metadata: fields not mentioned keep their current values, and an empty value clears the field. Every referenced field must already exist in the product environment. Conditional metadata rules are evaluated as part of the update.
Inputs
metadata_update_requestobjectrequired- The structured metadata values to assign and the assets to assign them to.
resource_typestringrequired- The type of resource (image, video, or raw).one of
imagevideoraw
No tools match.