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 Desktop 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 Desktop's own tool-permission prompt before it runs.

📘 New here? The Installation, Commands & Testing Guide walks through install, configuration, every tool with examples, and how to test against a live API.

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 it on demand):

{
  "mcpServers": {
    "cloudsee-drive": {
      "command": "npx",
      "args": ["-y", "@webapper/cloudsee-drive-mcp"],
      "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.

Related MCP server: AWS S3 MCP Server

Installation

npx (above) always runs the latest version. To install the cloudsee-drive-mcp binary globally instead:

npm install -g @webapper/cloudsee-drive-mcp

Requires Node.js ≥ 20. No native dependencies — works on macOS, Linux, and Windows.

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

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.

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 recent_files instead — their StorageId is a persisted id from the search index and stays stable across calls.

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.

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/shares return short-lived pre-signed URLs, never AWS credentials.

• 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 handles files of any size: a single pre-signed PUT up to 8 MiB, and multipart (8 MiB parts) above that — chosen automatically.

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