Skip to main content
Glama
CloudSee Drive MCP Server

CloudSee Drive MCP Server

CloudSee Drive MCP server

CI npm License: MIT

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>.mcpb

Packing 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-mcp

A 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-mcp

The 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

CLOUDSEE_API_KEY_ID

✅

—

Your CloudSee Drive API key id.

CLOUDSEE_API_KEY_SECRET

✅

—

The matching API key secret. Never commit this.

CLOUDSEE_API_BASE_URL

—

https://drive-api.cloudsee.cloud

API base URL. UAT: https://drive-api-uat.cloudsee.cloud.

CLOUDSEE_DEFAULT_BUCKET

—

—

Default drive (S3 bucket) for tool calls that omit bucketName. Find the name in the CloudSee dashboard.

CLOUDSEE_LOG_LEVEL

—

info

error | warn | info | debug. At debug, every API request + response is logged to stderr (secret redacted) for auditing.

CLOUDSEE_TIMEOUT_MS

—

30000

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_buckets

List the account's registered drives

read

list_files

List all files in a drive (recursive)

read

browse_folder

List a folder's contents (indexed view)

read

search_files

Find files/folders by name keyword

read

recent_files

List recently used files

read

get_file_metadata

Get a file's metadata

read

get_file_tags

Get a file's S3 tags

read

download_file

Get a temporary pre-signed download URL

download

share_link

Create a revocable CloudSee share page link, expiring after a chosen number of hours (default 12)

write

upload_file

Upload a file — see Uploading

write

upload_status

Progress of a large upload running in the background (stdio only)

write

create_folder

Create a folder

write

rename_file

Rename a file/folder

write · confirm

move_file

Move (or copy) a file/folder

write · confirm (move)

duplicate_file

Duplicate a file

write

delete_files

Permanently delete objects

delete · confirm

update_metadata

Update a file's metadata

write · confirm

restore_archived_file

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)

localPath

The server, off your own disk

Any — over 8 MiB it uploads in 16 MiB parts

hosted (a remote connector)

content + encoding

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, use U+202F before AM/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_file call does not pre-approve a later delete_files call — 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_link returns a CloudSee-hosted share page, not a storage URL: the API records the share with an explicit expiry (expiredTimeUTC) and a shareId, 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_ID and CLOUDSEE_API_KEY_SECRET after 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, or CLOUDSEE_DEFAULT_BUCKET). Without one, drive-scoped tools return a clear "specify a drive" message. list_buckets returns the drives your key can access — use it to discover drive names.

  • browse_folder/search_files use the search-indexed view and can return empty for un-indexed content — use list_files for 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 clear insufficient_scope message.

  • rename_file, move_file (and copy) and delete_files are queued operations: the tool returns a queue RequestId and the operation completes in the background, typically within 1–2 minutes — verify by listing.

  • upload_file differs 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 MCP

The 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 tools
browse_folderBrowse folderA
Read-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 filesA
Destructive

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 fileA
Read-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 metadataA
Read-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 tagsA
Read-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 versionA
Read-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 drivesA
Read-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 driveA
Read-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 fileA
Destructive

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 filesA
Read-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 folderA
Destructive

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 fileA
Destructive

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 filesA
Read-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 metadataA
Destructive

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 uploadA
Read-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

    A4.3/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables browsing S3 buckets and objects, and generating secure presigned URLs for downloads and uploads, through natural language commands in MCP clients like Claude Desktop.
      3
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables advanced file system operations such as file read/write, directory management, search, archiving, and file watching through natural language.
      16
      3
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables management of Google Drive files, Docs, Sheets, and Slides through natural language using MCP, with support for file operations, search, and shared drives.
      13 npm
      MIT