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:

custom provider

For any backend not covered by rclone. Fields:

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