Rclone

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 generated from the rclone-openapi spec and call rclone through the rclone-sdk client. There are 102 tools, organized into selectable toolsets, and each release targets one rclone version.

Prerequisites

rclone 1.75.2 or later, on the PATH. rclone-mcp starts it for you, with your normal rclone.conf, and stops it when the client disconnects. It listens on 127.0.0.1 with a random port and login.

If your MCP client can't find rclone, set PATH in the server's env, such as "PATH": "/opt/homebrew/bin:/usr/bin:/bin". If your rclone.conf is encrypted, set RCLONE_CONFIG_PASS there too.

To use an rclone that's already running, set RCLONE_URL. Do this if transfers need to outlast the client, because stopping rclone stops its background jobs, mounts and serves.

rclone rcd --rc-user=admin --rc-pass=secret

Each release targets one rclone version, and rclone-mcp refuses anything older.

Installation

Cursor / Claude Desktop (stdio)

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

{

"mcpServers": { "rclone": { "command": "npx", "args": ["-y", "rclone-mcp"] } } }

With an rclone that's already running

{

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

Docker

docker build -t rclone-mcp .

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

The image doesn't include rclone, so RCLONE_URL is required here.

Streamable HTTP transport

For web-based MCP clients, or to share one server:

npx rclone-mcp http --port 3000

This listens on 127.0.0.1 and only answers to local hostnames and origins. Every tool can reach your remotes, so listening anywhere else needs a token, which clients send as Authorization: Bearer :

RCLONE_MCP_TOKEN=<a long random string> npx rclone-mcp http --host 0.0.0.0

Use a TLS proxy in front of it on any network you don't trust, because the token and your data travel unencrypted otherwise. A proxy on the same machine can forward to the default host, as long as a token is set.

Browser pages can only use the server from origins you list in --allowed-origins. Clients that aren't browsers don't need this.

Configuration

Environment Variables

CLI Arguments

rclone-mcp [command]

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

Options: --url A running rclone to use. Without one, rclone-mcp starts its own --toolsets Comma-separated list of toolsets --read-only Only expose tools that change nothing and return no credentials --max-output The most characters of output a tool call returns

HTTP options: --port Port to listen on (default: 3000) --host Address to listen on (default: 127.0.0.1) --token Bearer token that clients must send. Prefer RCLONE_MCP_TOKEN --allowed-origins Comma-separated browser origins that can use the server --session-timeout Seconds a session can sit idle before it closes (default: 1800)

Toolsets

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

Special values:

• default — the five default toolsets (core, config, operations, sync, jobs)
• all — every toolset, including dangerous

The dangerous toolset

These tools only appear if you ask for them, whichever path they're on. They return credentials, control the rclone process, or can do damage that's hard to undo:

Examples

# Default toolsets (53 tools)

npx rclone-mcp

Everything (102 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, a tool is only registered if it changes nothing and returns no credentials, whichever toolsets you pick. So config_dump, options_get and serve_list are left out as well as sync_copy and operations_delete.

One limit remains: job_status returns the output of any job that rclone still remembers. If another client ran config/dump in the background in the last minute, its output would be visible.

Tool Annotations

Every tool declares readOnlyHint and destructiveHint, so clients can ask for confirmation before anything that could delete or overwrite data. Copies count as destructive, because they can overwrite files at the destination.

Long-Running Calls

Calls that can take a while, such as sync_copy, accept run_in_background: true. They return a job ID right away, and job_status reports progress.

Without it, the call waits until rclone finishes. If the client times out or cancels first, rclone cancels the transfer, so use run_in_background for anything long. A server you run yourself also stops answering a single call after an hour, unless you change --rc-server-write-timeout.

job_list returns the newest 100 job IDs from each list, with runningTotal and finishedTotal giving the full counts. Pass limit for a different number, and status for only running or only finished jobs. Rclone counts every call as a job, including job_status and job_list themselves, so the newest IDs aren't always work you started.

Limits

• Its own rclone stops with it: without RCLONE_URL, each rclone-mcp process starts its own rclone, and background jobs, mounts and serves stop with that process. With stdio, that means each client gets its own, and they don't see each other's jobs. Sessions on one HTTP server share one rclone. If rclone-mcp is killed with SIGKILL, its rclone keeps running until you stop it.
• Sessions: the HTTP transport keeps up to 100 sessions, closing the longest-idle one to make room. Its client gets a 404 and starts a new session, as the MCP spec describes.
• Output: a call returns at most 100,000 characters, with a note when it's cut. Ask for less, or raise RCLONE_MCP_MAX_OUTPUT.
• Unknown fields: a field that a route doesn't document is an error, because rclone would ignore it without saying so. Routes that accept extra options, such as serve_start, allow them.
• Uploads: operations_uploadfile takes file contents as text or base64 in the call, so it suits small files. Use operations_copyurl or sync_copy for anything large.

Upgrading from 1.x

• Without RCLONE_URL, rclone-mcp now starts its own rclone instead of connecting to http://localhost:5572. To keep using a server on that address, set RCLONE_URL to it.
• rclone older than 1.75.2 is refused.
• Fields now go in as real objects, so opt and parameters are objects rather than JSON strings.
• _async is gone. Use run_in_background on the tools that offer it.
• jobs is on by default, and the dangerous tools aren't.
• --read-only no longer exposes config_dump, config_get, options_get, options_info, serve_list, core_bwlimit, operations_publiclink or cache_fetch.
• The HTTP transport listens on 127.0.0.1 by default.
• Node 22.19 or later is required.

License

MIT

Made with ☁️ for the rclone community