Couchdrop

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

Tools

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

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