rclone-mcp

MCP (Model Context Protocol) server for the Rclone RC API. Gives AI assistants the ability to manage cloud storage remotes, copy/sync files, list directories, and more — all through natural language.

Tools are auto-generated from the rclone-openapi spec using the rclone-sdk client. 98 endpoints, organized into selectable toolsets.

Prerequisites

A running rclone remote control daemon:

bash

rclone rcd --rc-no-auth
# or with auth:
rclone rcd --rc-user=admin --rc-pass=secret

Installation

Cursor / Claude Desktop (stdio)

Add to your .cursor/mcp.json or claude_desktop_config.json:

json

{
  "mcpServers": {
    "rclone": {
      "command": "npx",
      "args": ["-y", "rclone-mcp"],
      "env": {
        "RCLONE_URL": "http://localhost:5572"
      }
    }
  }
}

With authentication

json

{
  "mcpServers": {
    "rclone": {
      "command": "npx",
      "args": ["-y", "rclone-mcp"],
      "env": {
        "RCLONE_URL": "http://localhost:5572",
        "RCLONE_USER": "admin",
        "RCLONE_PASS": "secret"
      }
    }
  }
}

Docker

bash

docker build -t rclone-mcp .

docker run -i --rm \
  -e RCLONE_URL=http://host.docker.internal:5572 \
  rclone-mcp

Streamable HTTP transport

For remote hosting or web-based MCP clients:

bash

npx rclone-mcp http --port 3000

Configuration

Environment Variables

Variable	Description	Default
`RCLONE_URL`	rclone RC daemon URL	`http://localhost:5572`
`RCLONE_USER`	HTTP Basic Auth username	—
`RCLONE_PASS`	HTTP Basic Auth password	—
`RCLONE_TOOLSETS`	Comma-separated toolset list	`default`
`RCLONE_READ_ONLY`	Set to `1` to disable write tools	—

CLI Arguments

rclone-mcp [command]

Commands:
  rclone-mcp stdio  Run with stdio transport (default)
  rclone-mcp http   Run with Streamable HTTP transport

Options:
  --toolsets   Comma-separated list of toolsets
  --read-only  Only expose read-only tools
  --port       HTTP port (http command only, default: 3000)

Toolsets

Tools are grouped by API path prefix. Enable only what you need to keep the tool list focused.

Toolset	Paths	Default
`core`	`/core/`, `/rc/`	Yes
`config`	`/config/*`	Yes
`operations`	`/operations/*`	Yes
`sync`	`/sync/*`	Yes
`jobs`	`/job/*`	No
`vfs`	`/vfs/*`	No
`mount`	`/mount/*`	No
`serve`	`/serve/*`	No
`cache`	`/cache/*`	No
`debug`	`/debug/*`	No
`backend`	`/backend/*`	No
`options`	`/options/*`	No
`plugins`	`/pluginsctl/*`	No
`fscache`	`/fscache/*`	No

Special values:

default — the four default toolsets (core, config, operations, sync)
all — every toolset

Examples

bash

# Default toolsets (55 tools)
npx rclone-mcp

# Everything (98 tools)
RCLONE_TOOLSETS=all npx rclone-mcp

# Just file operations and config
npx rclone-mcp --toolsets operations,config

# Default + mount
npx rclone-mcp --toolsets default,mount

# Read-only mode (no copy, delete, sync, etc.)
npx rclone-mcp --read-only

Read-Only Mode

When --read-only or RCLONE_READ_ONLY=1 is set, only non-mutating tools are registered. This excludes operations like file copy/move/delete, sync, config creation, mount/unmount, etc. Useful for giving AI assistants safe, read-only access.