couchdrop-mcp

Local stdio MCP server for Couchdrop. It lets MCP clients list Couchdrop files, inspect file metadata, download and upload files, list users and groups, and read folder permissions.

Requirements

• Node.js 22 or newer
• A Couchdrop API token

Couchdrop Token

Create or retrieve an API token from your Couchdrop account, then provide it to the server as COUCHDROP_API_TOKEN. Keep the token in your local MCP client configuration or shell environment. Do not commit it to source control.

Use a token with the narrowest access that fits your workflow.

Install And Configure

You can run the package with npx; no global install is required.

Claude Desktop

Add the server to your Claude Desktop MCP configuration, then restart Claude Desktop.

{
  "mcpServers": {
    "couchdrop": {
      "command": "npx",
      "args": ["-y", "couchdrop-mcp"],
      "env": {
        "COUCHDROP_API_TOKEN": "your-couchdrop-api-token"
      }
    }
  }
}

Codex

Codex reads MCP servers from ~/.codex/config.toml or a trusted project .codex/config.toml.

[mcp_servers.couchdrop]
command = "npx"
args = ["-y", "couchdrop-mcp"]

[mcp_servers.couchdrop.env]
COUCHDROP_API_TOKEN = "your-couchdrop-api-token"

Generic MCP Client

Configure the client to start a stdio server with this command:

{
  "command": "npx",
  "args": ["-y", "couchdrop-mcp"],
  "env": {
    "COUCHDROP_API_TOKEN": "your-couchdrop-api-token"
  }
}

If your client prefers an installed binary, install the package and run couchdrop-mcp as the stdio command.

Environment Variables

Variable	Required	Default	Description
COUCHDROP_API_TOKEN	Yes	None	Couchdrop API token sent to Couchdrop API and FileIO requests.
COUCHDROP_API_BASE	No	https://api.couchdrop.io	Base URL for Couchdrop management API requests.
COUCHDROP_FILEIO_BASE	No	https://fileio.couchdrop.io	Base URL for Couchdrop FileIO requests.
COUCHDROP_MAX_INLINE_BYTES	No	65536	Maximum bytes returned inline for downloads without outputPath.

Tools

All Couchdrop paths must start with /. Path segments must not contain ...

Tool	Arguments	Description
couchdrop_list_files	path optional, default /	Lists files and folders at a Couchdrop path.
couchdrop_get_file_info	path required	Gets metadata for a Couchdrop file or folder.
couchdrop_download_file	path required, outputPath optional	Downloads a file. Without outputPath, returns small UTF-8 text inline. With outputPath, saves the file locally.
couchdrop_upload_file	localPath required, destinationPath required	Uploads a local file to a Couchdrop path.
couchdrop_list_users	None	Lists Couchdrop users visible to the token.
couchdrop_list_groups	None	Lists Couchdrop groups visible to the token.
couchdrop_get_folder_permissions	path required	Gets permissions for a Couchdrop folder path.

Safety Notes

• Tokens stay local to your MCP client configuration or environment. This server does not persist tokens.
• v0.1 exposes no delete, move, chmod, user mutation, or group mutation tools.
• couchdrop_upload_file writes to the requested destinationPath; check the path before calling it.
• Use outputPath for large or binary downloads. Inline downloads are intended for small UTF-8 text files.
• In v0.1, uploads and downloads saved with outputPath are buffered in memory before being sent or written.

Local Development

npm install
npm run typecheck
npm test
npm run build
npm run dev

To inspect the package contents before publishing:

npm run build
npm pack --dry-run

Contributing

Contributions are welcome. Keep changes small, add or update tests for behavior changes, and run the local verification commands before opening a pull request.

Do not commit real Couchdrop tokens, generated secrets, or private customer paths in tests or documentation.

License

MIT