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 — with explicit confirmation before anything destructive happens.

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

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 ≥ 18. No native dependencies — works on macOS, Linux, and Windows.

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.

| Tool | Description | Access | | --- | --- | --- | | list_buckets | List accessible buckets | 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 shareable, time-limited link | download | | upload_file | Upload a local file (≤ 8 MiB) | 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 |

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; you must call again with confirm: true to proceed. This is 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.
• 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 drive-bridge /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.
• Read & download tools are functional today once a drive is given — list_files, get_file_metadata, get_file_tags, download_file, share_link all return real data.
• list_buckets currently returns an empty list (drive enumeration isn't wired for public API keys yet), so supply the drive name from the CloudSee dashboard for now.
• 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/share tools are present but their end-to-end authorization is sequenced behind the gateway's RBAC/scope wiring (CSD-572). Until that lands, the gateway may deny these operations — the tools surface that cleanly; it is expected, not a bug here.
• upload_file supports single-file uploads up to 8 MiB; multipart (larger files) is planned.

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