Unix 스타일의 셸, 스크립트 작성이 가능한 CLI, 그리고 Cloudinary 에셋을 로컬 파일 시스템처럼 관리할 수 있는 MCP server를 제공합니다.
다른 이름 Sheldon1999/cldsh-Cloudinary-Shell, cloudinary-shell
- 스타
- 0
- Tools
- 11
- 다운로드, 30일
- —
- 최신 버전
- 2.0.1
- 마지막 커밋
- 2026년 10월 28일
- 라이선스
- MIT
Cloudinary Shell MCP란?
Cloudinary Shell은(는) MCP server입니다. Unix 스타일의 셸, 스크립트 작성이 가능한 CLI, 그리고 Cloudinary 에셋을 로컬 파일 시스템처럼 관리할 수 있는 MCP server를 제공합니다. 11개 도구를 제공합니다. 예: cloudinary_list, cloudinary_tree, cloudinary_info.
프로젝트 README에서 생성된 요약
Cloudinary Shell MCP server 정보
Cloudinary Shell은 Unix 스타일의 셸, 스크립트 작성이 가능한 CLI, 그리고 MCP server를 통해 Cloudinary 에셋을 관리할 수 있는 통합 인터페이스를 제공합니다. 개발자는 dynamic 및 fixed 폴더 모드를 모두 지원하며, 마치 로컬 파일 시스템을 사용하는 것처럼 Cloudinary 계정과 상호작용할 수 있습니다. 이 도구는 단일 Node.js 바이너리로 구축되었으며 인증을 위해 API key 또는 Cloudinary URL이 필요하므로, Python 런타임이나 OAuth 브라우저 흐름이 필요하지 않습니다.
Claude Desktop, Claude Code 또는 Cursor를 사용하는 AI agent는 MCP server를 활용하여 에셋 목록 조회, 파일 업로드, 전달 URL 생성 등의 작업을 수행할 수 있습니다. 이 server에는 에셋 삭제나 이동과 같은 파괴적인 작업에 대해 2단계 확인 프로세스를 거치는 등 내장된 안전 메커니즘이 포함되어 있습니다. 자동화를 위해 CLI는 CI/CD 파이프라인 및 커스텀 스크립트 통합을 용이하게 하는 머신 리더블 JSON 출력과 특정 종료 코드를 제공합니다.
활용 사례
- 1CI/CD 내 에셋 관리 자동화개발자는 CLI를 사용하여 단일 명령으로 빌드 디렉토리를 특정 Cloudinary 폴더에 업로드할 수 있습니다.
- 2대화형 에셋 탐색 및 미리보기개발자는 대화형 셸을 사용하여 폴더를 탐색하고, 탭 완성 기능을 사용하며, 터미널에서 이미지 또는 비디오 썸네일을 직접 확인할 수 있습니다.
- 3스크립트용 에셋 메타데이터 추출도구의 JSON 출력을 다른 유틸리티로 파이프하여 파일 크기와 같은 특정 기준에 따라 에셋을 필터링할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Cloudinary Shell MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Cloudinary Shell MCP 설치
$ claude mcp add cldsh-cloudinary-shell -- npx -y cloudinary-shellCursor에 Cloudinary Shell MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"cldsh-cloudinary-shell": {
"command": "npx",
"args": [
"-y",
"cloudinary-shell"
]
}
}
}VS Code에 Cloudinary Shell MCP 설치
.vscode/mcp.json
{
"servers": {
"cldsh-cloudinary-shell": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"cloudinary-shell"
]
}
}
}VS Code CLI에 Cloudinary Shell MCP 설치
$ code --add-mcp '{"name":"cldsh-cloudinary-shell","type":"stdio","command":"npx","args":["-y","cloudinary-shell"]}'Claude Desktop에 Cloudinary Shell MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"cldsh-cloudinary-shell": {
"command": "npx",
"args": [
"-y",
"cloudinary-shell"
]
}
}
}Codex에 Cloudinary Shell MCP 설치
$ codex mcp add cldsh-cloudinary-shell -- npx -y cloudinary-shellCodex config.toml에 Cloudinary Shell MCP 설치
~/.codex/config.toml
[mcp_servers.cldsh-cloudinary-shell] command = "npx" args = ["-y", "cloudinary-shell"]
Gemini CLI에 Cloudinary Shell MCP 설치
$ gemini mcp add -s user cldsh-cloudinary-shell npx -- -y cloudinary-shellGemini settings.json에 Cloudinary Shell MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"cldsh-cloudinary-shell": {
"command": "npx",
"args": [
"-y",
"cloudinary-shell"
]
}
}
}Cloudinary Shell MCP 도구 11
README에서 감지됨cloudinary_listcloudinary_treecloudinary_infocloudinary_get_urlcloudinary_uploadcloudinary_downloadcloudinary_movecloudinary_deletecloudinary_mkdircloudinary_rename_foldercloudinary_account
| cloudinary_list | — | |
| cloudinary_tree | — | |
| cloudinary_info | — | |
| cloudinary_get_url | — | |
| cloudinary_upload | — | |
| cloudinary_download | — | |
| cloudinary_move | — | |
| cloudinary_delete | — | |
| cloudinary_mkdir | — | |
| cloudinary_rename_folder | — | |
| cloudinary_account | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능sheldon1999/cldsh-cloudinary-shell is public and reachablegithub.com/sheldon1999/cldsh-cloudinary-shell ↗통과
- 패키지가 이 저장소를 소스로 명시cloudinary-shell names sheldon1999/cldsh-cloudinary-shell as sourcenpmjs.com/package/cloudinary-shell ↗통과
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-28github.com/sheldon1999/cldsh-cloudinary-shell ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from cloudinary-shell통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음4 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음11 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기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.
cldsh |
cloudinary-cli (official) |
@cloudinary/* MCP (official) |
community MCP servers | |
|---|---|---|---|---|
| Runtime | Node, npx |
Python, pipx/Docker |
Node, npx per package |
Node, npx |
| Auth | API key / .env |
OAuth login | OAuth (hosted) or API key | API key |
Interactive shell (cd, ls, tab completion) |
✅ | ❌ one-shot flags | ❌ not a CLI | ❌ not a CLI |
| MCP server | ✅ same binary | ❌ | ✅ (5 separate packages) | ✅ |
| Confirm before delete/move/overwrite | ✅ two-step token, --dry-run |
❌ | — | ❌ |
| 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.
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 --json
Install 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 |
|---|---|---|
cloudinary_list |
List folders and assets (wildcards allowed) | path, resource_type, delivery_type, max |
cloudinary_tree |
Folder tree | folder, depth, resource_type, max_files |
cloudinary_info |
Full metadata of one asset | public_id, resource_type, delivery_type |
cloudinary_get_url |
Delivery URL, optionally transformed or signed | public_id, transformation, signed, resource_type |
cloudinary_upload |
Upload a local file or directory | local_path, name, folder, recursive, overwrite, resource_type, dry_run |
cloudinary_download |
Download assets to the local disk | public_id, destination, overwrite, dry_run |
cloudinary_move |
Move or rename an asset or folder | source, target, overwrite, change_public_id, dry_run |
cloudinary_delete |
Delete assets, or folders with recursive |
target, recursive, resource_type, dry_run |
cloudinary_mkdir |
Create a folder | folder |
cloudinary_rename_folder |
Rename or move a folder (dynamic folder mode) | from, to |
cloudinary_account |
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 --yes
Quote 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 video
- The 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 |
|---|---|
login [profile] [URL] [--stdin] |
Connect an account and save it as a profile (checked with Cloudinary first) |
config [ls | use <profile> | rm <profile>] |
Show the active account and which sources it overrides; list, switch or remove profiles |
ls [path|pattern] [-l] |
List folders and assets |
cd, pwd |
Change and show the current Cloudinary folder (shell only) |
lcd, lpwd |
Change and show the local directory |
mkdir <folder>... |
Create folders (parents included) |
upload <path> [name] [--to folder] [-r] |
Upload a file or a directory |
download <name|pattern>... [destination] [-f] |
Download assets |
mv <source> <target> [-o] [--public-id] |
Move or rename an asset or folder |
info <name> |
Asset metadata (-v for the full API response) |
url <name|pattern>... [--t=...] [--signed] |
Delivery URLs |
view <name> (alias preview) |
Show an image or video thumbnail in the terminal |
open <name> |
Open an asset in the browser |
rm [-r] <name|folder|pattern>... [-y] |
Delete assets, or folders with -r |
tree [folder] [-d N] |
Folder tree |
quota |
Remaining Admin API requests this hour and the folder mode |
mcp |
Check the MCP server |
Options shared by many commands:
| Option | Meaning |
|---|---|
--rt=image|video|raw|all |
Resource type. Listings show all types by default. |
--type=upload|private|authenticated |
Delivery type |
--dry-run |
Show what would happen without changing anything |
-y, --yes |
Don't ask for confirmation |
--json |
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.txt
- The 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 folder
- Unsigned 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 overrides
Profiles 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 environment- A
.envfile in the current directory - The 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 |
|---|---|
Not connected to a Cloudinary account |
Run cldsh login, or set CLOUDINARY_URL. cldsh config shows what is active. |
| The wrong account is used | cldsh config lists the source in use and the ones it overrides. |
Refusing to run "rm" on ... names that all exist in the local directory |
Your shell expanded a wildcard; quote it: cldsh rm 'cld*'. |
needs an interactive terminal / exit code 4 |
The command wants a confirmation; add --yes in scripts. |
matches 2 assets |
Add --rt=image (or video/raw) or use the public ID. |
| Rate limit reached | cldsh quota shows when the hourly budget resets. |
License
MIT. See CHANGELOG.md for changes between versions.
Cloudinary Shell MCP 질문
Cloudinary Shell MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add cldsh-cloudinary-shell -- npx -y cloudinary-shell를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Cloudinary Shell MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Cloudinary Shell MCP는 어떤 도구를 제공하나요?
11개 도구를 제공합니다. 예: cloudinary_list, cloudinary_tree, cloudinary_info, cloudinary_get_url, cloudinary_upload.
Cloudinary의 두 가지 폴더 모드를 모두 지원하나요?
네, 계정에서 dynamic folders를 사용하는지 또는 기존의 fixed folders를 사용하는지 자동으로 감지합니다.
삭제와 같은 파괴적인 작업에 대한 안전 장치가 있나요?
네, 삭제나 이동과 같은 파괴적인 도구는 미리보기를 반환하며, 변경 사항을 확정하려면 확인 토큰을 사용해야 합니다.
자동화 스크립트에 사용할 수 있나요?
네, CI/CD 통합을 위해 JSON 출력과 유의미한 종료 코드를 지원하는 스크립트용 CLI를 제공합니다.