Lets an AI client upload, download, list, modify, and delete files in Google Cloud Storage buckets.
Also known as pulsemcp/mcp-servers, remote-filesystem-mcp-server
- Stars
- 81
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.1.5
- Last commit
- Oct 9, 2026
- License
- MIT
What is Remote Filesystem MCP?
Remote Filesystem lets an AI client upload, download, list, modify, and delete files in Google Cloud Storage buckets. It exposes 4 tools, such as source, path, prefix.
Summary generated from the project's README
About Remote Filesystem MCP server
Managing cloud storage files through an AI client is what remote-filesystem enables for developers working with Google Cloud Storage. It allows an AI to perform filesystem-like operations such as uploading, downloading, listing, modifying, and deleting files directly within a GCS bucket. This server can be run locally via npx or installed through npm to connect your AI interface to remote storage.
Users can configure the server using environment variables like GCS_BUCKET and GCS_PROJECT_ID. Authentication is flexible, supporting inline credentials with GCS_CLIENT_EMAIL and GCS_PRIVATE_KEY, a path to a JSON key file via GOOGLE_APPLICATION_CREDENTIALS, or Application Default Credentials. To enhance security, you can use GCS_ROOT_PATH to restrict access to a specific directory or use ENABLED_TOOLGROUPS to limit the AI to readonly permissions. The server also includes tools for generating signed URLs for private files and managing metadata or public access settings.
What you can do with it
- 1Transferring local files to the cloudAsk your AI to upload a specific local file to a designated path in your Google Cloud Storage bucket.
- 2Retrieving binary or text dataInstruct the AI to download a file from your bucket as either plain text or base64 encoded data.
- 3Managing file permissions and metadataHave the AI change a file from private to public or update its custom metadata properties.
- 4Restricting AI access levelsConfigure the server so the AI can only view and download files without the ability to delete or upload.
Written from the project's README. Every use case is checked against a quote from it.
How to install Remote Filesystem MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Remote Filesystem MCP in Claude Code
$ claude mcp add --env 'GCS_BUCKET=<GCS_BUCKET>' --env 'GCS_PRIVATE_KEY=<YOUR_GCS_PRIVATE_KEY>' remote-filesystem -- npx -y remote-filesystem-mcp-serverInstall Remote Filesystem MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"remote-filesystem": {
"command": "npx",
"args": [
"-y",
"remote-filesystem-mcp-server"
],
"env": {
"GCS_BUCKET": "<GCS_BUCKET>",
"GCS_PRIVATE_KEY": "<YOUR_GCS_PRIVATE_KEY>"
}
}
}
}Install Remote Filesystem MCP in VS Code
.vscode/mcp.json
{
"servers": {
"remote-filesystem": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"remote-filesystem-mcp-server"
],
"env": {
"GCS_BUCKET": "<GCS_BUCKET>",
"GCS_PRIVATE_KEY": "<YOUR_GCS_PRIVATE_KEY>"
}
}
}
}Install Remote Filesystem MCP in VS Code CLI
$ code --add-mcp '{"name":"remote-filesystem","type":"stdio","command":"npx","args":["-y","remote-filesystem-mcp-server"],"env":{"GCS_BUCKET":"<GCS_BUCKET>","GCS_PRIVATE_KEY":"<YOUR_GCS_PRIVATE_KEY>"}}'Install Remote Filesystem MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"remote-filesystem": {
"command": "npx",
"args": [
"-y",
"remote-filesystem-mcp-server"
],
"env": {
"GCS_BUCKET": "<GCS_BUCKET>",
"GCS_PRIVATE_KEY": "<YOUR_GCS_PRIVATE_KEY>"
}
}
}
}Install Remote Filesystem MCP in Codex
$ codex mcp add remote-filesystem --env 'GCS_BUCKET=<GCS_BUCKET>' --env 'GCS_PRIVATE_KEY=<YOUR_GCS_PRIVATE_KEY>' -- npx -y remote-filesystem-mcp-serverInstall Remote Filesystem MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.remote-filesystem] command = "npx" args = ["-y", "remote-filesystem-mcp-server"] [mcp_servers.remote-filesystem.env] GCS_BUCKET = "<GCS_BUCKET>" GCS_PRIVATE_KEY = "<YOUR_GCS_PRIVATE_KEY>"
Install Remote Filesystem MCP in Gemini CLI
$ gemini mcp add -s user -e 'GCS_BUCKET=<GCS_BUCKET>' -e 'GCS_PRIVATE_KEY=<YOUR_GCS_PRIVATE_KEY>' remote-filesystem npx -- -y remote-filesystem-mcp-serverInstall Remote Filesystem MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"remote-filesystem": {
"command": "npx",
"args": [
"-y",
"remote-filesystem-mcp-server"
],
"env": {
"GCS_BUCKET": "<GCS_BUCKET>",
"GCS_PRIVATE_KEY": "<YOUR_GCS_PRIVATE_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Remote Filesystem MCP tools 4
Detected from the READMEsourcepathprefixmetadata
Configuration
GCS_BUCKETRequiredGoogle Cloud Storage bucket name.
GCS_PRIVATE_KEYSecretService account private key for inline credentials.
ENABLED_TOOLGROUPSComma-separated tool groups: readonly or readwrite.
GCS_CLIENT_EMAILService account email for inline credentials.
GCS_MAKE_PUBLICMake uploaded files publicly accessible.
GCS_PROJECT_IDGoogle Cloud project ID.
GCS_ROOT_PATHRoot path prefix to restrict access within bucket.
GOOGLE_APPLICATION_CREDENTIALSPath to Google Cloud service account key file.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubRemote 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": "sa@project.iam.gserviceaccount.com",
"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: Onlydownloadandlist_filestools are availablereadwrite: 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)
GCS_CLIENT_EMAIL=sa@project.iam.gserviceaccount.com
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
Remote Filesystem MCP questions
How do I add Remote Filesystem MCP to Claude Code?
Run claude mcp add --env 'GCS_BUCKET=<GCS_BUCKET>' --env 'GCS_PRIVATE_KEY=<YOUR_GCS_PRIVATE_KEY>' remote-filesystem -- npx -y remote-filesystem-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Remote Filesystem MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Remote Filesystem MCP provide?
It exposes 4 tools, including source, path, prefix, metadata.
Which cloud storage providers does Remote Filesystem MCP support?
It currently supports Google Cloud Storage, with plans for S3, Cloudflare R2, and more.
How do I authenticate the GCS bucket connection?
You can use inline credentials (client email and private key), a service account key file, or Application Default Credentials.
Can I restrict access to a subfolder of the bucket?
Yes, set GCS_ROOT_PATH to a root path prefix to restrict access within the bucket.
Can I limit the server to read-only operations?
Yes, set ENABLED_TOOLGROUPS=readonly so only the download and list_files tools are available.
Can I download binary files?
Yes, pass asBase64 to the download tool to get binary data returned as base64.