remote-files

MCP server for monitoring remote file sources, detecting new files, and extracting content. Works with any storage backend via rclone (70+ providers) or custom commands.

Features

• Multi-source monitoring — track multiple remote locations (Google Drive, S3, SFTP, local dirs, etc.)
• New file detection — state-based diffing detects new and changed files
• Content extraction — extracts text from DOCX, PDF, and plain text files
• Auto-cleanup — downloaded files are deleted after content extraction
• Hybrid transport — built-in rclone support + custom shell commands

Prerequisites

• Node.js >= 18
• npm
• rclone (if using the rclone transport — the installer can install it for you)

Installation

The interactive installer handles dependencies, build, configuration, and Claude Code registration:

cd remote-files
bash install.sh

The installer will:

1. Verify Node.js and npm are available
2. Ask you to choose a transport mode (rclone or custom)
3. Install rclone if needed (via brew, apt, pacman, or the official install script)
4. Walk you through rclone remote configuration if no remotes exist yet
5. Install npm dependencies and build the project
6. Create the config file at ~/.config/remote-files/config.json
7. Register the MCP server with Claude Code (if the CLI is available)

Manual installation

If you prefer to set things up yourself:

cd remote-files
npm install
npm run build
claude mcp add --transport stdio remote-files -- node /absolute/path/to/remote-files/dist/index.js

Then create ~/.config/remote-files/config.json manually (see Configuration below).

Configuration

Create ~/.config/remote-files/config.json:

{
  "sources": {
    "my-drive": {
      "provider": "rclone",
      "remote": "gdrive:",
      "path": "Documents/Reports",
      "flags": ["--drive-shared-with-me"],
      "exclude": ["*.tmp"],
      "excludeFrom": "/path/to/exclude-patterns.txt"
    },
    "my-server": {
      "provider": "custom",
      "listCommand": "ssh server 'find /data -type f -printf \"%s %P\\n\"'",
      "downloadCommand": "scp server:/data/$FILE $DEST/"
    }
  },
  "settings": {
    "tempDir": "/tmp/remote-files",
    "stateDir": "~/.local/share/remote-files/state",
    "autoCleanup": true,
    "maxContentLength": 102400
  }
}

Override config path with REMOTE_FILES_CONFIG env var.

rclone provider

Requires rclone installed and configured. Fields:

Field	Required	Description
remote	yes	rclone remote name (e.g. gdrive:, s3:)
path	yes	Path within the remote
flags	no	Extra rclone flags
exclude	no	Exclude patterns
excludeFrom	no	Path to exclude file

custom provider

For any backend not covered by rclone. Fields:

Field	Required	Description
listCommand	yes	Shell command that outputs <size> <path> lines
downloadCommand	yes	Shell command with $FILE and $DEST variables

MCP Tools

check_sources

Check for new/changed files without downloading.

Parameters:
  source?          — specific source name (omit for all)
  include_pattern? — glob filter (e.g. "*.docx")

init_source

Initialize a source baseline. All current files are marked as known.

Parameters:
  source — source name to initialize

fetch_file

Download a file, extract text, and auto-delete the local copy.

Parameters:
  source     — source name
  path       — file path (from check_sources)
  keep_local — if true, keep file on disk (default: false)

Returns extracted text for DOCX/PDF/TXT. For unknown formats, returns local_path for Claude to read directly.

Workflow

1. First time: Claude calls init_source to create a baseline
2. Ongoing: Claude calls check_sources to find new files
3. Per file: Claude calls fetch_file to get content and summarize
4. Files are auto-deleted after extraction

Uninstall

claude mcp remove remote-files
rm -rf ~/.config/remote-files
rm -rf ~/.local/share/remote-files