cldsh
Provides MCP tools for managing a Cloudinary account like a file system, including listing assets and folders, getting asset metadata and delivery URLs, uploading and downloading files, moving or renaming assets and folders, creating folders, and deleting assets or recursive folders with previews and confirmation before destructive changes.
Cloudinary Shell (cldsh)
MCP server, interactive shell and scriptable CLI for Cloudinary

cldsh lets you work with a Cloudinary account like a file system:
AI agents (Claude Desktop, Claude Code, Cursor) get Cloudinary tools through the Model Context Protocol (MCP), with previews and confirmation before anything is deleted or replaced.
Developers get an interactive shell with folders, tab completion, history and inline image previews.
Scripts and CI get single commands with JSON output and meaningful exit codes.
It works with both Cloudinary folder modes: dynamic folders (every account created since June 2024) and the older fixed folders. The mode is detected automatically.
Working on a project that uses Cloudinary? Give
INTEGRATION.mdto your AI agent or team: integration patterns (Next.js, React, Node.js, Python), transformation recipes andcldshworkflows.
How cldsh compares
Cloudinary also publishes an official CLI (cloudinary-cli, Python) and official MCP packages (@cloudinary/*). cldsh is a separate, independent project built for a different workflow: one Node binary that is a shell, a scriptable CLI and an MCP server together, authenticated with your existing API key — no Python runtime, no OAuth browser flow, no hosted service required.
|
|
| community MCP servers | |
Runtime | Node, | Python, | Node, | Node, |
Auth | API key / | OAuth login | OAuth (hosted) or API key | API key |
Interactive shell ( | ✅ | ❌ one-shot flags | ❌ not a CLI | ❌ not a CLI |
MCP server | ✅ same binary | ❌ | ✅ (5 separate packages) | ✅ |
Confirm before delete/move/overwrite | ✅ two-step token, | ❌ | — | ❌ |
Fixed/dynamic folder mode | ✅ auto-detected | not documented | not documented | not documented |
Pick cldsh for one local tool, API-key auth and a safety net on AI-driven changes. Pick the official packages for Cloudinary-maintained, domain-split MCP servers with OAuth and enterprise support.
Related MCP server: @nogoo9/mcp-server-cloud-fs
Quick start
Requires Node.js 20 or newer and a Cloudinary account (cloud name, API key and API secret, or a CLOUDINARY_URL).
# AI agents: add the MCP server to Claude Code
claude mcp add cloudinary npx -y cloudinary-shell --mcp
# Developers: open the interactive shell
npx cloudinary-shell
# Scripts: run one command
npx cloudinary-shell ls products --jsonInstall globally to get the shorter cldsh command: npm install -g cloudinary-shell.
MCP server (for AI agents)
cldsh --mcp runs an MCP server over stdio (JSON-RPC 2.0). It supports protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
Client setup
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"cloudinary": {
"command": "npx",
"args": ["-y", "cloudinary-shell", "--mcp"]
}
}
}Claude Code: claude mcp add cloudinary npx -y cloudinary-shell --mcp
Cursor: Settings → MCP → Add new MCP server, type command, command npx -y cloudinary-shell --mcp.
Check the setup with cldsh mcp: it runs the handshake, lists the tools and makes a live call on your account.
Tools
Tool | What it does | Main arguments |
| List folders and assets (wildcards allowed) |
|
| Folder tree |
|
| Full metadata of one asset |
|
| Delivery URL, optionally transformed or signed |
|
| Upload a local file or directory |
|
| Download assets to the local disk |
|
| Move or rename an asset or folder |
|
| Delete assets, or folders with |
|
| Create a folder |
|
| Rename or move a folder (dynamic folder mode) |
|
| Cloud name, folder mode, credential source, remaining API budget | — |
Every tool carries MCP annotations (read-only, destructive, idempotent), so clients can decide when to ask you.
Safety
Two-step changes.
cloudinary_delete,cloudinary_move,cloudinary_rename_folder, and uploads that would replace existing assets first return a preview with aconfirm_token. Nothing changes until the agent calls again with the same arguments and that token. Tokens are single-use, expire after 5 minutes and stop working if the account changes.dry_run: trueonly previews.Local files. Uploads and downloads can only reach the folder the server was started in, the folders your MCP client shares as roots, and folders added with
--allow-path. The cldsh credentials folder,~/.sshand hidden files (unless named explicitly) are always refused. Downloads never overwrite a local file unlessoverwrite: true.Server options:
--read-only: only the read-only tools (list, tree, info, get_url, account).--allow-path <dir>: allow another local folder (repeatable).--no-confirm: run changes in one call, as in cldsh 1.x. Use only for trusted automation.
"args": ["-y", "cloudinary-shell", "--mcp", "--read-only"]Command line (for scripts and CI)
Run any command directly: cldsh <command> [arguments] [options].
Results go to stdout; progress, warnings and errors go to stderr.
--jsonprints machine-readable JSON on stdout (errors are printed as JSON on stderr).Exit codes:
0success,1error,2wrong usage,3partly failed (for example 2 of 50 uploads failed),4needs confirmation (add--yes) or was cancelled.--profile <name>uses a saved profile for one command.
# Upload a build folder with subfolders
cldsh upload ./dist/assets -r --to site/assets
# CDN URLs of every asset in a folder
cldsh ls portfolio --json | jq -r '.files[].secure_url'
# Assets larger than 100 KB
cldsh ls portfolio --json | jq -r '.files[] | select(.bytes > 100000) | .public_id'
# Preview a delete, then run it without the question
cldsh rm 'old-*' --dry-run
cldsh rm -r archive/2023 --yesQuote wildcards. Your shell expands an unquoted
cld*into local file names beforecldshsees it. Writecldsh rm 'cld*'. If every name given tormexists in the local directory,cldshrefuses and reminds you.
Interactive shell
Run cldsh with no arguments.
Connected to Cloudinary account: my-cloud (global credentials profile (default))
[my-cloud]$~ cd products
[my-cloud]$~/products ls -l
SIZE(KB) DIMENSIONS(px) NAME FORMAT TYPE
──────── ────────────── ──────── ────── ─────
245 1200x630 hero png image
15 512x512 logo svg image
1830 1920x1080 promo mp4 videoThe prompt shows the account (and profile) and the current folder.
Tab completes commands, options, folder paths (
cd apps/<Tab>) and asset names.History is kept across sessions in
~/.cldsh_history(private file; lines with credentials are never saved).Paths are relative to the current folder;
/or~is the root,..goes up,cd -goes back.helplists all commands;help <command>lists all options of one command.
Commands
Command | What it does |
| Connect an account and save it as a profile (checked with Cloudinary first) |
| Show the active account and which sources it overrides; list, switch or remove profiles |
| List folders and assets |
| Change and show the current Cloudinary folder (shell only) |
| Change and show the local directory |
| Create folders (parents included) |
| Upload a file or a directory |
| Download assets |
| Move or rename an asset or folder |
| Asset metadata ( |
| Delivery URLs |
| Show an image or video thumbnail in the terminal |
| Open an asset in the browser |
| Delete assets, or folders with |
| Folder tree |
| Remaining Admin API requests this hour and the folder mode |
| Check the MCP server |
Options shared by many commands:
Option | Meaning |
| Resource type. Listings show all types by default. |
| Delivery type |
| Show what would happen without changing anything |
| Don't ask for confirmation |
| JSON output |
Assets can be named by their name in the current folder, by path (products/hero), by public ID, or as asset_id:<id>. If a name matches several assets (for example an image and a video called intro), cldsh lists them; add --rt or use the public ID.
Uploading
[my-cloud]$~/products upload ~/Pictures/hero.png
Uploaded (created): https://res.cloudinary.com/my-cloud/image/upload/v1730000000/products/hero.png
[my-cloud]$~ upload ./media -r --to campaigns/fall
[1/3] created https://res.cloudinary.com/my-cloud/image/upload/.../campaigns/fall/banner.png
[2/3] created https://res.cloudinary.com/my-cloud/video/upload/.../campaigns/fall/teaser.mp4
[3/3] created https://res.cloudinary.com/my-cloud/raw/upload/.../campaigns/fall/notes.txtThe resource type comes from the file extension: images (including PDF and SVG) → image, video and audio → video, everything else → raw.
--rtoverrides it.Images and videos get a public ID without extension; raw files keep it (
notes.txt).-rincludes subdirectories as subfolders. Dotfiles are skipped.Existing assets are overwritten and reported as
overwritten;--no-overwritekeeps them (skipped).When two files would get the same public ID (
photo.jpg,photo.png), both get their extension as suffix (photo_jpg,photo_png).Files over 20 MB are uploaded in chunks with progress; temporary failures are retried.
--dry-runshows the planned public IDs and works without credentials.
Deleting
[my-cloud]$~/products rm hero
deleted products/hero
Deleted 1 · not found 0 · failed 0
[my-cloud]$~ rm -r campaigns/fall
Delete 3 assets (1 image, 1 video, 1 raw, 2.1 MB) and 1 folder in cloud my-cloud:
...
Proceed? [y/N]rm -rdeletes everything in the folder and its subfolders (all resource and delivery types), then the folder.Recursive deletes, wildcard deletes and deletes of more than 20 assets show the plan and ask first. Emptying the whole account asks you to type the cloud name.
-yskips the question; scripts need--yes.Every asset is reported as
deleted,not foundorfailed, and the exit code is3if anything was not found or failed.--skip-backupdeletes folders that still hold backups of deleted assets.
Moving and renaming
[my-cloud]$~/products mv hero archive/
Moved: /products/hero -> /archive/hero (URL unchanged)Dynamic folder mode: moving and renaming keep the delivery URL (the folder and display name change).
--public-idalso renames the public ID, which changes the URL. Folders can be moved and renamed:mv products catalog/products.Fixed folder mode: the folder is part of the public ID, so moving or renaming changes the URL. Cloudinary can't move folders in this mode.
An existing target stops the move;
-ogoes ahead. In dynamic mode,-oonly replaces an asset with the same public ID; an asset that merely has the same name is kept.--dry-runshows whether the URL will change.
URLs, previews and downloads
url hero # delivery URL
url hero --t="f_auto,q_auto,w_800" # with a transformation
url 'banner-*' # several assets
url private-doc --signed # signed URL for authenticated assets
view hero --t="e_grayscale" # inline preview (iTerm2, WezTerm, Ghostty, VS Code, Warp)
download 'shots/*' ./shots/ # several files into a folderUnsigned URLs without
--tare exactly the asset'ssecure_url.viewprints the preview URL when the terminal can't show images.downloadskips local files that already exist unless-f; private and authenticated assets download through signed URLs.
Accounts and credentials
# Interactive (the secret is not shown while you type)
cldsh login
# From a script, without putting the secret in your shell history
printf %s "$CLOUDINARY_URL" | cldsh login prod --stdin
cldsh config ls # saved profiles
cldsh config use prod # switch (also inside the shell)
cldsh config # active account, where it comes from, what it overridesProfiles are stored in ~/.config/cldsh/credentials.json (%APPDATA%\cldsh on Windows) with owner-only permissions. Writes are atomic, and a damaged file is never overwritten (login --reset moves it aside).
When several sources are present, the strongest wins:
--profile <name>,config use/loginin the current shell, orCLOUDINARY_PROFILECLOUDINARY_URL(orCLOUDINARY_CLOUD_NAME,CLOUDINARY_API_KEY,CLOUDINARY_API_SECRET) in the environmentA
.envfile in the current directoryThe saved default profile
cldsh warns at startup, and config shows, when a source is overridden. CLOUDINARY_URL options such as ?upload_prefix=https://api-eu.cloudinary.com (EU/AP data centers) and private CDN settings are supported.
Folder modes and API limits
cldshdetects the folder mode of your account. Override it with--folder-mode=fixed|dynamicorCLDSH_FOLDER_MODE.Listing folders and assets uses Cloudinary's Admin API, which is rate-limited per hour (500 requests on the Free plan).
cldshcaches listings for a few seconds, warns when less than 10% of the hourly budget is left, andquotashows the remaining requests. Uploads and delivery URLs don't count.In fixed folder mode, listing a folder also pages through its subfolders' assets, so very large folders cost more requests.
Troubleshooting
Problem | What to do |
| Run |
The wrong account is used |
|
| Your shell expanded a wildcard; quote it: |
| The command wants a confirmation; add |
| Add |
Rate limit reached |
|
License
MIT. See CHANGELOG.md for changes between versions.
Available Tools
11 toolscloudinary_accountAccount and server statusARead-onlyIdempotent
The connected Cloudinary account (cloud name, folder mode, where the credentials come from, remaining Admin API requests) and this server's safety settings.
Inputs: no named parameters. Returns: object
cloudinary_deleteDelete assets or foldersADestructiveIdempotent
Delete an asset, the matches of a wildcard, or (with recursive) a folder and everything in it. The first call returns needs_confirmation with the full plan and a confirm_token; nothing is deleted until the call is repeated with that token.
Inputs: target (required), dry_run, recursive, confirm_token, +2 more. Returns: object
cloudinary_downloadDownload assetsADestructiveIdempotent
Download assets (name, public ID or wildcard) into a local directory or file inside the allowed local directories. Existing files are skipped unless overwrite is true.
Inputs: public_id (required), dry_run, overwrite, destination, +2 more. Returns: object
cloudinary_get_urlGet delivery URLARead-onlyIdempotent
Build CDN delivery URLs for assets, optionally with a transformation (e.g. "f_auto,q_auto", "w_800,c_limit").
Inputs: public_id (required), signed, delivery_type, resource_type, +1 more. Returns: object
cloudinary_infoAsset detailsARead-onlyIdempotent
Full metadata of one asset: dimensions, bytes, format, tags, version, created date, URLs.
Inputs: public_id (required), delivery_type, resource_type. Returns: object
cloudinary_listList folderARead-onlyIdempotent
List the subfolders and assets of a Cloudinary folder (paths start at the root), or the matches of a wildcard such as "cld*" or "shots/*.png".
Inputs: max, path, delivery_type, resource_type. Returns: object
cloudinary_mkdirCreate folderAIdempotent
Create a folder (missing parent folders are created too).
Inputs: folder (required). Returns: object
cloudinary_moveMove or renameADestructive
Move or rename an asset, or move a folder (dynamic folder mode). In dynamic folder mode an asset move keeps its URL unless change_public_id is set. The first call returns needs_confirmation with the plan and a confirm_token.
Inputs: source (required), target (required), dry_run, overwrite, +4 more. Returns: object
cloudinary_rename_folderRename folderADestructive
Rename or move a folder with everything in it (dynamic folder mode only; asset URLs do not change). The first call returns needs_confirmation with the plan and a confirm_token.
Inputs: to (required), from (required), dry_run, confirm_token. Returns: object
cloudinary_treeFolder treeBRead-onlyIdempotent
Folder hierarchy with the assets of each folder, starting at a folder (default: root).
Inputs: depth, folder, max_files, resource_type. Returns: object
cloudinary_uploadUpload filesADestructive
Upload a local file or directory (inside the allowed local directories) into a Cloudinary folder. The resource type follows the file extension unless resource_type is set. If the upload would replace existing assets, the first call returns needs_confirmation with a confirm_token instead of uploading.
Inputs: local_path (required), name, folder, dry_run, +4 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools target a clearly distinct operation (get_url, info, upload, download, delete, mkdir, account). Two pairs blur: cloudinary_move explicitly also moves folders, which overlaps cloudinary_rename_folder, and cloudinary_tree overlaps cloudinary_list since the tree includes per-folder asset listings; the descriptions mitigate but do not fully eliminate the misselection risk.
Every tool uses the same cloudinary_ prefix with snake_case, which is highly predictable. Minor deviation: most names are verb-based (get_url, list, upload) while a few are bare nouns (info, tree, account), so the pattern isn't perfectly uniform.
11 tools sits squarely in the well-scoped range and each maps to a real asset-management need (listing, metadata, transfer, folder ops, account state). Nothing appears redundant enough to drop.
The core lifecycle is covered: browse (list/tree/info), transfer (upload/download), organize (mkdir/move/rename_folder), remove (delete), URL generation, and account introspection, with a consistent confirmation flow for destructive ops. Gaps exist around asset metadata updates (tags are reported by info but there is no tool to set them) and explicit asset rename/public_id changes outside move.
Maintenance
Related MCP Connectors
Manage Cloudinary upload presets, named transformations, mappings, triggers, and streaming profiles.
Browse, search, upload, tag, transfer, and delete images in your Raster libraries over MCP.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Official ImageKit media library server: search, upload, organize, tag, share and manage assets.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that provides an interface for interacting with the Cloudinary API to manage media assets and cloud configurations. It enables secure resource management through API keys and OAuth2 authentication within MCP-compliant environments.-
- FlicenseNot gradedqualityDmaintenanceA cloud replacement for mcp-server-filesystem that provides 30 tools for S3, Azure Blob, and Google Cloud Storage, deployable locally via STDIO or remotely over HTTP/WebSocket with OAuth 2.1 authentication.101 npm3-
- AlicenseCqualityCmaintenanceIt exposes the full official Immich API (276 tools across 41 groups) to MCP clients, letting them search and manage assets, albums, people, tags, memories, shared links, users, jobs and admin settings. It supports file uploads and downloads, stdio or streamable HTTP transports, and filtering/read-only safety modes.276MIT
- AlicenseAqualityBmaintenanceSelectel S3 MCP server and Go CLI: browse, preview and restore files in a bucket. Read-only by default; write, delete and admin tools only behind switches, destructive calls confirmed by a person.13MIT