CloudSee Drive MCP Server
CloudSee Drive MCP server lets an AI assistant browse, search, download, share, upload, organize, tag, and delete files in your CloudSee Drive (S3) buckets — with destructive actions gated behind confirmation prompts.
Discover drives —
list_bucketslists the drives your API key can access (drive name =bucketName).Browse & list files —
list_files(complete, recursive, straight from storage),browse_folder(indexed folder view),search_files(keyword search),recent_files(newest first); all paginated with cursors.Inspect files —
get_file_metadata(size, type, timestamps, storage class) andget_file_tags(S3 tags).Download —
download_filereturns a short-lived pre-signed URL (no bytes loaded into the conversation).Share —
share_linkcreates a revocable CloudSee share page with an expiry (default 12h, capped at 30 days).Upload —
upload_filereads a local path (any size, auto multipart over 8 MiB, background for large files, never overwrites);upload_statustracks background uploads (stdio only).Organize —
create_folder,rename_file,move_file(or copy),duplicate_file.Delete —
delete_filespermanently removes one or more objects.Metadata & tags —
update_metadataedits category/description/project and tags in merge or replace mode.Archive —
restore_archived_filestarts a Glacier un-archive (Expedited/Standard/Bulk).Diagnostics —
get_versionreports the running connector version, tool count, and API host.Safety rails — delete/rename/move/update-metadata/restore need
confirm: trueplus the client's own tool-permission prompt; write/delete tools requiredrive:write/drive:deleteAPI scopes.
Allows management of files and folders in Amazon S3 buckets via the CloudSee Drive interface, including browsing, searching, uploading, downloading, sharing, renaming, moving, deleting, and updating metadata and tags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CloudSee Drive MCP Server Search for files named 'budget' in my drive"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CloudSee Drive MCP server
An open-source Model Context Protocol (MCP) server for CloudSee Drive — connect your CloudSee account (a browser interface for Amazon S3) to Claude and any MCP-compatible client, and manage your files in natural language.
Browse, search, download, share, upload, organize, and tag your CloudSee Drive files from your AI assistant — every destructive action must be approved through Claude's own tool-permission prompt before it runs.
Two ways to connect
Remote connector (recommended) | Local server (this package) | |
Runs on | Webapper's hosted infrastructure | Your own machine |
Works in | claude.ai web, Claude Desktop, Claude mobile | Claude Desktop, Claude Code, any stdio MCP client |
Sign-in | OAuth — your CloudSee account, no keys to copy | CloudSee API key id + secret |
Setup | Click Connect, sign in | Edit config / install the extension |
Uploads | Up to 256 KB per file | Any size (reads your disk) |
Remote connector — no install: in Claude, open Settings → Connectors, find
CloudSee Drive (or choose Add custom connector and enter
https://drive-mcp.cloudsee.cloud/mcp), click Connect, and sign in with your CloudSee
account. That's the whole setup.
📘 Full guide — install, authentication, security model, data handling, FAQ, troubleshooting:
docs/CONNECTOR.md.
Local server: keeps everything on your machine and handles large uploads — continue below. 📘 The Installation, Commands & Testing Guide walks through install, configuration, every tool with examples, and how to test against a live API.
Related MCP server: AWS S3 MCP Server
Quickstart (≈5 minutes)
1. Get an API key
In the CloudSee Drive dashboard, create a public-API key. You'll receive a key id
(looks like AKIA…) and a secret. Copy both — the secret is shown only once.
2. Add the server to Claude Desktop
Open Claude Desktop → Settings → Developer → Edit Config, and add a cloudsee-drive
entry under mcpServers (no install needed — npx fetches the package on demand). Keep the
@latest suffix: it makes npm resolve the published version instead of running an older copy
it finds already installed on your PATH.
{
"mcpServers": {
"cloudsee-drive": {
"command": "npx",
"args": ["-y", "@webapper/cloudsee-drive-mcp@latest"],
"env": {
"CLOUDSEE_API_KEY_ID": "<your key id>",
"CLOUDSEE_API_KEY_SECRET": "<your secret>",
"CLOUDSEE_API_BASE_URL": "https://drive-api.cloudsee.cloud"
}
}
}
}3. Restart Claude Desktop and try it
"List my CloudSee buckets, then show the most recent files."
That's it. The server runs locally on your machine; your API key never leaves it.
Installation
Requires Node.js ≥ 20. No native dependencies — works on macOS, Linux, and Windows.
As a Claude Desktop extension (no config file)
The server is packaged as an MCP Bundle (.mcpb) — a one-click install that asks for your
API key in a form instead of making you edit JSON. Build one from this repo with:
npm run build:mcpb # → build/cloudsee-drive-<version>.mcpbPacking needs the MCPB CLI (npm i -g @anthropic-ai/mcpb); without it the script still stages
the bundle and prints the one command left to run. Open the resulting .mcpb with Claude
Desktop to install it.
As an npm package
npm install -g @webapper/cloudsee-drive-mcpA global install does not update itself — re-run that command to move to a newer release.
Pinning or upgrading the npm version pins the server; a client keeps the tool list it fetched
when it connected, so remove and re-add (or restart) the connector after an upgrade, and ask
get_version what is actually running before reporting on a tool's behaviour.
Or let npx fetch the package for you, as in the Quickstart above;
the @latest suffix used there is what makes npm resolve the published version rather than a
global install that happens to be on PATH.
On macOS that command usually fails the first time with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@webapper'. That is npm's global prefix pointing at a directory
your user cannot write to — it is not specific to this package, and any system configured the
same way behaves the same. Either install with sudo, or point npm at a prefix you own:
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH" # add to ~/.zshrc or ~/.bashrc to keep it
npm install -g @webapper/cloudsee-drive-mcpThe npx form in the quickstart above sidesteps this entirely — it needs no global install.
Configuration
All configuration is via environment variables (set them in the Claude Desktop env block,
or a local .env for development — see .env.example).
Variable | Required | Default | Description |
| ✅ | — | Your CloudSee Drive API key id. |
| ✅ | — | The matching API key secret. Never commit this. |
| — |
| API base URL. UAT: |
| — | — | Default drive (S3 bucket) for tool calls that omit |
| — |
|
|
| — |
| Per-request timeout in milliseconds. |
Tools
Most tools operate on one drive (an S3 bucket): pass bucketName, or set
CLOUDSEE_DEFAULT_BUCKET once and omit it. recent_files and list_buckets don't need a drive.
The local (stdio) server exposes 19 tools; the hosted remote connector exposes 18 —
upload_status is stdio-only, and the hosted upload_file takes the file's contents instead
of a path (see Uploading).
Tool | Description | Access |
| List the account's registered drives | read |
| List all files in a drive (recursive) | read |
| List a folder's contents (indexed view) | read |
| Find files/folders by name keyword | read |
| List recently used files | read |
| Get a file's metadata | read |
| Get a file's S3 tags | read |
| Get a temporary pre-signed download URL | download |
| Create a revocable CloudSee share page link, expiring after a chosen number of hours (default 12) | write |
| Upload a file — see Uploading | write |
| Progress of a large upload running in the background (stdio only) | write |
| Create a folder | write |
| Rename a file/folder | write · confirm |
| Move (or copy) a file/folder | write · confirm (move) |
| Duplicate a file | write |
| Permanently delete objects | delete · confirm |
| Update a file's metadata | write · confirm |
| Un-archive a Glacier object | write · confirm |
Uploading
upload_file has one name and two shapes, chosen by how the server is reached — you only
ever see the one that applies:
Running as | Argument | Who reads the bytes | Size |
stdio (this package, Claude Desktop / Claude Code) |
| The server, off your own disk | Any — over 8 MiB it uploads in 16 MiB parts |
hosted (a remote connector) |
| The bytes travel in the request | ≤ 256 KB |
Files over 8 MiB upload in the background. An MCP client abandons a tool call after 60
seconds, so a large upload cannot be waited on — it would be reported as a timeout while it was
still succeeding. upload_file therefore returns an id straight away and keeps going; ask
upload_status for progress. The file is in the drive once that says completed. Parts go up
four at a time.
The upload lives in this server process, so quitting the MCP client cancels it.
The hosted shape exists because a remote server has no access to your disk, and a remote MCP client is normally blocked from uploading to storage itself. For anything larger than a few hundred kilobytes on a hosted connector, use the CloudSee web app.
Both shapes behave the same in two ways that matter:
Nothing is ever overwritten. If the name is taken, the file is stored with a timestamp appended (
report (30-07-2026 14:05).md) and the tool tells you the name it used.The content type comes from the file name, matching what storage signs the upload URL with. Passing your own would risk a signature mismatch, so the tool doesn't accept one.
Tip for
localPath: copy the name exactly. File names can contain characters that look like a plain space but aren't — macOS screen recordings, for instance, useU+202FbeforeAM/PM. When a file isn't found, the error points at the near match and names the character.
list_files ids are not stable — don't use them for mutation
list_files lists straight from storage and mints a new object id on every call. Never pass
that id to rename_file, move_file, update_metadata, or delete_files. Use search_files,
browse_folder, or get_file_metadata instead — their StorageId is a persisted id from the
search index and stays stable across calls. recent_files is not a source either: the id
it returns belongs to a different id space and those tools reject it.
Destructive operations require confirmation
Tools marked confirm (delete, rename, move, update-metadata, restore) use two-step
confirmation: the first call returns a preview and makes no changes; the model must call
again with confirm: true to proceed. The two-step call itself is filled in by Claude, not by
you — it is not the actual approval gate.
The real gate is Claude Desktop's own tool-permission prompt, which appears before any tool call runs. Four things worth knowing about it:
Denying it genuinely stops the operation — the tool is never invoked with
confirm: true.Approving one destructive call does not approve a different one. Approving a
rename_filecall does not pre-approve a laterdelete_filescall — each call is gated independently."Allow for this task" is the prompt's default button, and once clicked it covers that tool for the rest of the current chat — later calls to the same tool in the same conversation won't prompt again. Choose "Allow once" to review every call individually.
This is still a client-side safety prompt — the CloudSee API authorizes every operation server-side; confirmation is not the security boundary.
Privacy Policy
Full text: PRIVACY.md · hosted copy
In short — the server is a conduit, not a destination:
What it processes. Only what a tool call needs: your API credentials (from the environment), and the file names, paths, metadata, tags or file contents involved in the operation you asked for.
What it stores. Nothing. There is no database, cache or log of your files; each request is handled in memory and forgotten. Diagnostics go to stderr with the secret redacted.
Who else sees it. Your AI client, which issues the tool calls, and the CloudSee Drive API / Amazon S3, which performs them. No analytics, no profiling, no model training, no resale.
Retention. None by this server. Files and account data live in CloudSee Drive under its own policy; downloads are short-lived pre-signed URLs, and a share is a CloudSee-hosted page whose share record carries its own expiry.
Contact. privacy@webapper.net · security reports per SECURITY.md.
Security
Your API key id + secret are read from the environment and held only in this local process. The server never logs the secret, never returns it in tool output, and never writes it to a file. All diagnostics go to stderr (stdout is the MCP transport).
File downloads return short-lived pre-signed URLs, never long-lived account credentials. (A pre-signed URL embeds the temporary, scoped signing token that is inherent to S3 SigV4 presigning — it expires with the link.)
share_linkreturns a CloudSee-hosted share page, not a storage URL: the API records the share with an explicit expiry (expiredTimeUTC) and ashareId, so it can be revoked before it expires. The raw share token the API mints is never rendered into tool output.Rotating an API key issues a new key id and secret together and revokes the old id immediately — update both
CLOUDSEE_API_KEY_IDandCLOUDSEE_API_KEY_SECRETafter rotating; see GUIDE.md §8 Troubleshooting.Report vulnerabilities per
SECURITY.md. Never paste a real key/secret into an issue.
Status & known limitations
This wraps CloudSee Drive's public API (the /v1/* gateway).
Almost every tool needs a drive (
bucketName, orCLOUDSEE_DEFAULT_BUCKET). Without one, drive-scoped tools return a clear "specify a drive" message.list_bucketsreturns the drives your key can access — use it to discover drive names.browse_folder/search_filesuse the search-indexed view and can return empty for un-indexed content — uselist_filesfor a complete, reliable listing of a drive.Write/delete tools require an API key whose scopes include
drive:write/drive:delete. Admin-created keys carry these scopes; keys created under a User role are read/download-only, and the gateway denies out-of-scope calls with a clearinsufficient_scopemessage.rename_file,move_file(and copy) anddelete_filesare queued operations: the tool returns a queueRequestIdand the operation completes in the background, typically within 1–2 minutes — verify by listing.upload_filediffers by transport (see Uploading). Over stdio it takes a path and handles any size — one pre-signed PUT up to 8 MiB, multipart above that. On a hosted connector it takes the file's contents instead, capped at 256 KB.
Development
npm install
npm test # vitest: unit + tool↔contract drift tests
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run build # tsup → dist/ (ESM, with bin shebang)
npm run sync:contract # regenerate contract/registry.snapshot.json from the API seed
node scripts/smoke.mjs # build first; spawns the server and lists tools over MCPThe contract-drift test (test/contract/drift.test.ts) fails the build if any tool drifts
from the committed API contract snapshot — so tool schemas can't silently diverge from the
real /v1/* surface.
License
MIT © Webapper
Available Tools
19 toolsbrowse_folderBrowse folderARead-only
List the files and sub-folders inside a folder of a drive (the indexed view), with sorting and pagination. Requires the drive (bucketName). To filter by keyword use 'search_files'; for a complete, recursive file listing straight from storage use 'list_files'. For a complete listing, keep calling with the returned cursor until no cursor comes back — a page may be short, or even empty, while more results remain.
Inputs: path, cursor, pageSize, bucketName, +1 more.
create_folderCreate folderA
Create a new folder at the given path in a drive. Requires the drive (bucketName). (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: name (required), parentPath (required), bucketName.
delete_filesDelete filesADestructive
Permanently delete one or more files/folders from a drive, each addressed by its exact object key plus its storage id (the StorageId field from search_files / browse_folder / get_file_metadata — not from list_files or recent_files, whose ids are a different id space and will NOT work). Queued: returns a RequestId per object and the deletes complete in the background, typically under 2 minutes — verify by listing until the objects disappear. Requires the drive (bucketName). Destructive and irreversible. Requires confirm=true. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: objects (required), confirm, bucketName.
download_fileDownload fileARead-only
Get a short-lived pre-signed download URL for a file. Requires the drive (bucketName). The URL is time-limited and grants read access to that one object — share it with care. Returns the URL; it does not load file bytes into the conversation.
Inputs: filePath (required), storageId, bucketName, forceDownload.
duplicate_fileDuplicate fileA
Create a copy of a file in the same location. Requires the drive (bucketName). (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: objectKey (required), storageId, bucketName.
get_file_metadataGet file metadataARead-only
Get detailed metadata for a single file or object (size, type, timestamps, storage class, and other attributes) by its object key. Requires the drive (bucketName).
Inputs: objectKey (required), bucketName.
get_file_tagsGet file tagsARead-only
Get the S3 object tags (key/value pairs) attached to a file, by object key. Requires the drive (bucketName).
Inputs: objectKey (required), bucketName.
get_versionServer versionARead-only
Report the version of this CloudSee Drive connector, how many tools it registered, and which CloudSee API host it is configured against. Answer this from the tool rather than from the package version you believe is installed: a client keeps the tool list it fetched when it connected, so an upgraded server can still be described by an older list until the connector is reconnected. Takes no arguments, makes no API call and never reports the API key or its secret.
Inputs: no named parameters.
list_bucketsList drivesARead-only
List the drives registered to the authenticated CloudSee Drive account that the caller is allowed to see. Use this first to discover available drives before browsing or searching; the Name of a drive is the bucketName the other tools expect.
Inputs: no named parameters.
list_filesList files in a driveARead-only
List the files in a drive straight from storage, recursively by default — the most reliable way to see what a drive actually contains. Requires the drive (bucketName). Returns names, sizes, storage classes and keys, with pagination. The object id in each result is regenerated on every call and must never be used for rename_file, move_file, update_metadata, or delete_files — use search_files, browse_folder, or get_file_metadata for a stable StorageId instead (recent_files returns a different id space and will not work there either). For a complete listing, keep calling with the returned cursor until no cursor comes back — a page may be short, or even empty, while more results remain.
Inputs: deep, cursor, pageSize, bucketName.
move_fileMove or copy fileADestructive
Move (or copy, with asCopy=true) a file or folder to a new location, addressed by its exact object key plus its storage id (the StorageId field from search_files / browse_folder / get_file_metadata — not from list_files or recent_files, whose ids are a different id space and will NOT work). Queued: returns a RequestId and the operation completes in the background, typically under 2 minutes — verify by listing until the object appears at the destination. Requires the source drive (bucketName). A move removes the source and is destructive, so it requires confirm=true; a copy does not. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: objectKey (required), storageId (required), destinationPath (required), asCopy, +4 more.
recent_filesRecent filesARead-only
List the account's most recently accessed or modified files, newest first, with pagination. For a complete listing, keep calling with the returned cursor until no cursor comes back.
Inputs: limit, cursor.
rename_fileRename file or folderADestructive
Rename a file or folder in a drive, addressed by its exact object key plus its storage id (the StorageId field from search_files / browse_folder / get_file_metadata — not from list_files or recent_files, whose ids are a different id space and will NOT work). Queued: returns a RequestId and the rename completes in the background, typically under 2 minutes — verify by listing until the new name appears. The StorageId goes stale while the rename is in flight, and StorageId is what delete_files and move_file require, so re-read it from a listing once the new name appears rather than reusing the one you renamed with. Requires the drive (bucketName). Destructive (changes the object's key). Requires confirm=true. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: newName (required), objectKey (required), storageId (required), confirm, +2 more.
restore_archived_fileRestore archived fileADestructive
Begin restoring an archived (S3 Glacier) object so it can be downloaded. Requires the drive (bucketName). This is Glacier un-archiving — NOT recovery of a deleted file — and may incur retrieval cost and take minutes to hours. Requires confirm=true. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: days (required), objectKey (required), storageId (required), confirm, +2 more.
search_filesSearch filesARead-only
Search for files and folders by name keyword within a drive (the indexed view). Requires the drive (bucketName). Returns matches with pagination. For a complete listing, keep calling with the returned cursor until no cursor comes back — a page may be short, or even empty, while more results remain.
Inputs: query (required), path, cursor, pageSize, +1 more.
update_metadataUpdate file metadataADestructive
Update a file's metadata (category / description / project) and tags in a drive, addressed by its storage id (the StorageId field from search_files / browse_folder / get_file_metadata — not from list_files or recent_files, whose ids are a different id space and will NOT work). Defaults to mode "merge": a metadata field you do not send is KEPT, a field sent as "" is CLEARED, and tags are merged by Key — a tag with the same Key is overwritten and tags with other Keys are kept. Destructive cases: sending tags: [] CLEARS every tag on the object, and mode "replace" clears every metadata field and every tag you do not send — that is also the only way to remove a single tag, by sending the complete set you want to keep. Requires the drive (bucketName) and confirm=true. Note: the update rewrites the object in place (S3 copy) — its ETag changes (and may change format) and LastModified is set to the update time; ETag-keyed caches and sync tools will see the object as new. Objects larger than 5 GiB are updated via multipart copy; objects larger than 8 GiB are rejected, because the rewrite cannot finish inside the API request timeout. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: storageId (required), mode, tags, confirm, +2 more.
upload_fileUpload fileA
Upload a file into a folder of a drive. The file is read from the machine running this server — which, over this connection, is your own machine — so pass its path. Requires the drive (bucketName). Files up to 8 MiB are sent in one piece; larger ones are split into parts automatically. If the name is already taken, a timestamped name is used instead, so an existing file is never overwritten. Indexing is asynchronous, so a file that uploaded successfully is still absent from browse_folder / search_files / list_files for a while afterwards — keep listing until it appears instead of uploading it again. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: localPath (required), fileName, bucketName, storageClass, +1 more.
upload_statusCheck a background uploadARead-only
Report progress on an upload started by 'upload_file' that was too large to finish inside one tool call. Give it the id upload_file returned, or omit the id to list every tracked upload. States are running, completed and failed; a file is only in the drive once its upload reports completed. This reads progress held in this server process and makes no API call, so it is safe to poll. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)
Inputs: uploadId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes, but the multiple listing tools (browse_folder, search_files, list_files, recent_files) overlap in function and could cause misselection if descriptions are not carefully read. However, each is explicitly scoped to different views (indexed vs. storage, keyword search, recent activity), so an agent can differentiate with attention.
All tool names follow a consistent verb_noun snake_case pattern (e.g., list_files, create_folder, delete_files, get_file_metadata). The verbs are clear and the objects are consistent, making naming highly predictable and easy to infer.
19 tools is on the higher end but appropriate for a cloud drive server, covering listing, searching, uploading, downloading, sharing, metadata management, and file lifecycle operations. Each tool has a clear role, and the count does not feel excessive or bloated.
The tool surface covers core CRUD operations (upload, list, get, update, delete) plus additional features like sharing, archiving, and upload status tracking. Notable gaps include lack of share revocation and no explicit tool for listing shares, but these are minor and can be worked around via the dashboard.
Maintenance
Related MCP Connectors
Search, organize and share the files in your S3-compatible buckets from your AI assistant.
1Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Browse, upload, download, copy, move and share files in your own S3-compatible buckets.
Browse, upload, download, and share files in your S3-compatible buckets with delegated roles.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Google Drive file operations (search, read, create, download, etc.) through natural language, compatible with Claude.ai's Drive connector.182MIT
- AlicenseAqualityDmaintenanceEnables browsing S3 buckets and objects, and generating secure presigned URLs for downloads and uploads, through natural language commands in MCP clients like Claude Desktop.34MIT
- AlicenseBqualityBmaintenanceEnables advanced file system operations such as file read/write, directory management, search, archiving, and file watching through natural language.163GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables management of Google Drive files, Docs, Sheets, and Slides through natural language using MCP, with support for file operations, search, and shared drives.13 npmMIT