Remote Filesystem MCP Server

An MCP server for remote filesystem operations on cloud storage providers. Currently supports Google Cloud Storage (GCS), with plans for S3, Cloudflare R2, and more.

Features

• Upload files to cloud storage with public/private access control
• Download files as text or base64 (for binary files)
• List files and directories with prefix filtering
• Modify file properties (public/private, content type, metadata)
• Delete files from remote storage
• Root path constraint to restrict access within bucket
• Toolset groups for permission-based access control
• Inline credentials support (no JSON key file needed)
• Signed URL generation for private files

Installation

npm install remote-filesystem-mcp-server

Or run directly with npx:

npx remote-filesystem-mcp-server

Configuration

Environment Variables

| Variable | Required | Description | Default | | -------------------------------- | -------- | ------------------------------------ | ------- | | GCS_BUCKET | Yes | GCS bucket name | - | | GCS_PROJECT_ID | No | Google Cloud project ID | Auto | | GCS_CLIENT_EMAIL | No* | Service account email (inline creds) | - | | GCS_PRIVATE_KEY | No* | Service account private key (inline) | - | | GOOGLE_APPLICATION_CREDENTIALS | No* | Path to service account key file | - | | GCS_ROOT_PATH | No | Root path prefix - restricts access | None | | GCS_MAKE_PUBLIC | No | Make files publicly accessible | false | | ENABLED_TOOLGROUPS | No | Tool groups: readonly, readwrite | All |

* One authentication method required: inline credentials OR key file OR ADC

Claude Desktop Configuration

{
  "mcpServers": {
    "remote-filesystem": {
      "command": "npx",
      "args": ["-y", "remote-filesystem-mcp-server"],
      "env": {
        "GCS_BUCKET": "your-bucket-name",
        "GCS_CLIENT_EMAIL": "[email protected]",
        "GCS_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...",
        "GCS_ROOT_PATH": "uploads/"
      }
    }
  }
}

Tools

upload

Upload a file to the remote filesystem.

Parameters:

| Parameter | Type | Required | Description | | ------------- | ------- | -------- | ----------------------------------------- | | source | string | Yes | File path (file://...) or base64 data | | path | string | No | Destination path (auto-generated if none) | | contentType | string | No | MIME type (auto-detected if not provided) | | makePublic | boolean | No | Override default public/private setting |

Example:

upload({
  source: 'file:///tmp/screenshot.png',
  path: 'screenshots/pr-123.png',
  makePublic: true,
});

download

Download a file from the remote filesystem.

Parameters:

| Parameter | Type | Required | Description | | ---------- | ------- | -------- | ---------------------------------- | | path | string | Yes | Path to the file | | asBase64 | boolean | No | Return as base64 (for binary data) |

Example:

download({
  path: 'screenshots/pr-123.png',
  asBase64: true,
});

list_files

List files and directories in the remote filesystem.

Parameters:

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------ | | prefix | string | No | Directory prefix to list | | maxResults | number | No | Maximum files to return |

Example:

list_files({
  prefix: 'screenshots/',
  maxResults: 100,
});

modify

Modify file properties.

Parameters:

| Parameter | Type | Required | Description | | ------------- | ------- | -------- | ------------------------- | | path | string | Yes | Path to the file | | makePublic | boolean | No | Make file public | | makePrivate | boolean | No | Make file private | | contentType | string | No | New MIME type | | metadata | object | No | Custom metadata key-value |

Example:

modify({
  path: 'reports/doc.pdf',
  makePublic: true,
  metadata: { author: 'claude' },
});

delete_file

Delete a file from the remote filesystem.

Parameters:

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------- | | path | string | Yes | Path to the file |

Example:

delete_file({
  path: 'temp/old-file.txt',
});

Toolset Groups

The server supports permission-based access control via tool groups:

• readonly: Only download and list_files tools are available
• readwrite: All tools are available (includes readonly tools)

Set ENABLED_TOOLGROUPS=readonly to restrict to read-only operations.

Authentication

The server supports multiple authentication methods:

1. Inline Credentials (Recommended)

[email protected]
GCS_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

2. Key File

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

3. Application Default Credentials (ADC)

gcloud auth application-default login

License

MIT