Skip to main content
Glama
rclone-mcp

rclone-mcp

by rclone-ui

rclone-mcp

Discord

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 98 tools, organized into selectable toolsets, and each release targets one rclone version.

Prerequisites

rclone 1.76.0 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.

Related MCP server: obsidian-mcp

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 <token>:

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

Variable

Description

Default

RCLONE_URL

A running rclone to use. Without it, rclone-mcp starts its own

—

RCLONE_USER

HTTP Basic Auth username for RCLONE_URL

—

RCLONE_PASS

HTTP Basic Auth password for RCLONE_URL

—

RCLONE_TOOLSETS

Comma-separated toolset list

default

RCLONE_READ_ONLY

Set to 1 to expose only tools that change nothing and return no credentials

—

RCLONE_MCP_MAX_OUTPUT

The most characters of output a tool call returns

100000

PORT

Port the HTTP transport listens on

3000

RCLONE_MCP_HOST

Address the HTTP transport listens on

127.0.0.1

RCLONE_MCP_TOKEN

Bearer token for the HTTP transport. Required unless it listens on localhost

—

RCLONE_MCP_ALLOWED_ORIGINS

Comma-separated browser origins that can use the HTTP transport

—

RCLONE_MCP_SESSION_TIMEOUT

Seconds an HTTP session can sit idle before it closes

1800

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.

Toolset

Paths

Default

core

/core/*, /rc/*

Yes

config

/config/*

Yes

operations

/operations/*

Yes

sync

/sync/*

Yes

jobs

/job/*

Yes

vfs

/vfs/*

No

mount

/mount/*

No

serve

/serve/*

No

cache

/cache/*

No

debug

/debug/*

No

backend

/backend/*

No

options

/options/*

No

fscache

/fscache/*

No

dangerous

See below

No

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:

Tool

Why

config_dump, config_get, options_get, options_info, serve_list

Return credentials, including rclone's own password

config_delete, config_password, config_setpath, config_unlock, config_unset, options_set

Change or remove configuration

core_command

Runs any rclone command

core_quit

Stops rclone

job_batch

Can call any route, including everything on this list

operations_purge

Deletes a directory and everything in it

Examples

# 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, 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. operations_getfile is left out too, because it reads any file that rclone can reach, and rclone.conf is one of them.

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

Available Tools

56 tools
config_createA

Create remote configuration — Creates a new remote in rclone.conf, mirroring rclone config create.

Inputs: opt, name, type, _async, +2 more.

config_deleteB

Delete remote configuration — Removes an existing remote from rclone.conf.

Inputs: name, _async, _group.

config_dumpA

Dump configuration — Returns the contents of the config file as a JSON object keyed by remote name.

Inputs: _async, _group.

config_getA

Get remote configuration — Returns the key/value settings for a single remote.

Inputs: name, _async, _group.

config_listremotesA

List configured remotes — Returns the names of all remotes defined in the config file.

Inputs: _async, _group.

config_passwordB

Update remote secrets — Sets obscured password fields for a remote configuration.

Inputs: name, _async, _group, parameters.

config_pathsA

Show config paths — Returns the paths to the config file, cache directory, and temporary directory.

Inputs: _async, _group.

config_providersB

List backend providers — Returns metadata describing each supported storage provider.

Inputs: _async, _group.

config_setpathB

Set config path — Points rclone at a specific rclone.conf file.

Inputs: path, _async, _group.

config_unlockA

Unlock encrypted config — Unlocks the configuration file using the provided password.

Inputs: _async, _group, configPassword.

config_updateC

Update remote configuration — Updates an existing remote with new parameter values.

Inputs: opt, name, _async, _group, +1 more.

core_bwlimitA

Get or update bandwidth limits — Reads the current bandwidth limit or applies a new schedule string, just like rclone rc core/bwlimit.

Inputs: rate, _async, _group.

core_commandB

Run an rclone command — Executes a standard rclone CLI command remotely and streams or returns its output.

Inputs: arg, opt, _async, _group, +2 more.

core_disksA

List locally accessible paths — Returns a list of locally accessible paths including mount points, user directories, and removable volumes.

Inputs: _async, _group.

core_duB

Report disk usage — Returns disk usage statistics for the supplied local directory (defaults to the cache dir).

Inputs: dir, _async, _group.

core_gcB

Force garbage collection — Triggers Go's garbage collector to release unused memory.

Inputs: _async, _group.

core_group_listB

List stats groups — Lists stats groups currently tracked by rclone.

Inputs: _async, _group.

core_memstatsA

Fetch runtime memory stats — Returns Go runtime memory statistics similar to runtime.ReadMemStats.

Inputs: _async, _group.

core_obscureB

Obscure a clear string — Obscures a plain-text secret for inclusion in rclone.conf.

Inputs: clear, _async, _group.

core_pidA

Return rclone PID — Returns the process ID of the running rclone instance.

Inputs: _async, _group.

core_quitA

Terminate rclone — Stops the rclone process, optionally supplying an exit code.

Inputs: _async, _group, exitCode.

core_statsB

Current stats snapshot — Returns active transfer statistics including bytes transferred, speed, and error counts.

Inputs: group, short, _async, _group.

core_stats_deleteB

Delete stats group — Deletes the counters associated with a specific stats group.

Inputs: group, _async, _group.

core_stats_resetA

Reset stats counters — Clears counters, errors, and finished transfers for the provided stats group or all groups.

Inputs: group, _async, _group.

core_transferredC

List completed transfers — Returns up to 100 recently completed transfers for the requested stats group.

Inputs: group, _async, _group.

core_versionA

Report rclone version — Returns the running rclone version, build metadata, and Go runtime details.

Inputs: _async, _group.

operations_aboutB

Get remote quota — Returns storage quota and usage details for the remote, equivalent to rclone about.

Inputs: fs, _async, _group.

operations_checkB

Compare source and destination — Compares source and destination trees, reporting matches, differences, and missing files.

Inputs: dstFs, error, match, srcFs, +11 more.

operations_cleanupB

Remove trashed files — Permanently removes trashed objects from the specified remote path.

Inputs: fs, _async, _group.

operations_copyfileB

Copy a single file — Copies one object from a source remote and path to a destination remote and path.

Inputs: dstFs, srcFs, _async, _group, +2 more.

operations_copyurlB

Copy from URL — Downloads a public URL and stores it at the requested remote path.

Inputs: fs, url, _async, _group, +2 more.

operations_deleteB

Delete objects in path — Deletes matching files and directories for the provided remote, honouring filters and config overrides.

Inputs: fs, _async, _group, _config, +1 more.

operations_deletefileA

Delete single file — Removes a specific object from the remote.

Inputs: fs, _async, _group, remote.

operations_fsinfoC

Describe remote capabilities — Returns backend features, hash support, metadata descriptions, and other info for the remote.

Inputs: fs, _async, _group.

operations_hashsumC

Generate hash sums — Produces a hash sum listing for files under the given path using the requested hash algorithm.

Inputs: fs, _async, _group, base64, +2 more.

operations_hashsumfileB

Hash a single file — Returns the hash of a single file using the specified hash algorithm.

Inputs: fs, _async, _group, base64, +3 more.

operations_listC

List objects — Lists objects and directories for a remote path, returning the same fields as rclone lsjson.

Inputs: fs, opt, _async, _group, +11 more.

operations_mkdirA

Create directory — Creates the target directory or container if it does not exist.

Inputs: fs, _async, _group, remote.

operations_movefileB

Move a single file — Moves one object from a source remote and path to a destination remote and path.

Inputs: dstFs, srcFs, _async, _group, +2 more.

operations_purgeB

Purge directory — Deletes a directory or container and all of its contents.

Inputs: fs, _async, _group, remote, +2 more.

operations_rmdirA

Remove empty directory — Deletes an empty directory or container.

Inputs: fs, _async, _group, remote.

operations_rmdirsA

Remove empty directories — Deletes empty subdirectories beneath the specified path, optionally leaving the root.

Inputs: fs, _async, _group, remote, +1 more.

operations_settierB

Change storage tier — Updates the storage class or tier for every object in the specified remote path.

Inputs: fs, _async, _group.

operations_settierfileB

Change file storage tier — Updates the storage class or tier for a single object.

Inputs: fs, _async, _group, remote.

operations_sizeB

Count remote size — Reports total size, file count, and number of objects without size metadata.

Inputs: fs, _async, _group.

operations_statB

Stat an object — Returns metadata for a single file or directory, mirroring rclone lsjson on one entry.

Inputs: fs, opt, _async, _group, +1 more.

operations_uploadfileB

Upload files via multipart — Accepts multipart/form-data payloads and writes the uploaded files to the specified remote path.

Inputs: fs, _async, _group, remote.

rc_errorA

Return a test error — Always returns an error response incorporating the supplied parameters, useful for testing error handling.

Inputs: _async, params.

rc_listA

List RC commands — Returns metadata about every available RC command, including whether authentication is required.

Inputs: _async, _group.

rc_noopA

Echo request parameters — Returns all supplied parameters unchanged so you can verify RC connectivity.

Inputs: _async, params.

rc_noop_authA

Echo parameters (auth required) — Same as rc/noop, but requires authentication to validate access control.

Inputs: _async, params.

sync_bisyncB

Bidirectional sync — Performs a bidirectional synchronisation between two paths, supporting safety checks and recovery options.

Inputs: force, path1, path2, _async, +18 more.

sync_copyA

Copy source to destination — Copies objects from a source remote to a destination remote without deleting destination files.

Inputs: dstFs, srcFs, _async, _group, +3 more.

sync_moveA

Move source to destination — Moves objects from a source remote to a destination remote, optionally cleaning up empty directories.

Inputs: dstFs, srcFs, _async, _group, +4 more.

sync_syncC

Sync source to destination — Synchronises a source remote to a destination remote, making the destination match the source.

Inputs: dstFs, srcFs, _async, _group, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 56 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, with detailed descriptions that prevent ambiguity even among similar operations like delete and deletefile or different sync modes.

    Naming Consistency5/5

    All tools follow a consistent category_action pattern (e.g., config_create, core_stats, operations_list), using snake_case throughout with no mixing of conventions.

    Tool Count3/5

    With 56 tools, the set is large and comprehensive, covering most rclone RC capabilities. While each tool has a specific use, the high count may overwhelm agents and is beyond the typical well-scoped range.

    Completeness5/5

    The tool surface covers all major rclone operations: configuration management, core utilities, file operations (CRUD, copy, move, sync), and RC introspection, with no obvious gaps for the advertised server purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Remote MCP server that gives AI agents read/write access to your Obsidian vaults, supporting both local desktop vaults and headless mode.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server for pCloud cloud storage. Enables AI assistants like Claude to interact with your pCloud - listing files, creating folders, searching, sharing, and more.
      15
      2
      GPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Rclone RC API that enables AI assistants to manage cloud storage remotes, copy/sync files, and list directories through natural language.
      12
      10 npm
      MIT