@nogoo9/mcp-server-cloud-fs

Cloud replacement for mcp-server-filesystem — 30 tools for S3, Azure Blob, and GCS.
Deploy locally via STDIO or remotely over HTTP/WebSocket with OAuth 2.1 auth.
Also available as an npm library and interactive TUI.

📖 Read the full documentation →

Providers: Amazon S3 · Azure Blob Storage · Google Cloud Storage · MinIO · RustFS · Cloudflare R2 · Backblaze B2 · Wasabi · LocalStack · SQLite · In-Memory

---

Table of Contents

• What it does
• Quick start
• Interactive Shell
• Transports
• Authentication & Authorization
• Production Features
• CLI Reference
• Provider Setup
• MCP Client Config
• Tool Reference
• Architecture: VFS
• Caching
• Programmatic Usage
• MCP Inspector
• Development & Testing
• AI Agent Skill
• Documentation
• License

---

What it does

@nogoo9/mcp-server-cloud-fs exposes all 14 tools defined by mcp-server-filesystem — same tool names, same parameter schemas — over cloud object storage. Drop it into any MCP client config that currently points at mcp-server-filesystem and your AI assistant gains read/write access to S3, Azure Blob Storage, or Google Cloud Storage buckets.

It also includes 5 extended tools inspired by claude-code's filesystem tool surface: line-range reads, byte-range chunk reads, in-process regex search (single file and multi-file), server-side copy, and opt-in deletion. Plus 6 cloud-native tools (presigned URLs, object metadata/tags, tag-based search, version history, version restore), 2 AI-native tools (schema extraction, file summarization), and 1 macro tool (patch_file for atomic diffs).

A Virtual Filesystem (VFS) layer provides FUSE-like cache coherence with ETag-based concurrency control, a shell tool lets you run POSIX-like commands (ls, grep, jq, cat | wc, etc.) against cloud storage, and the package is available as a programmatic npm library.

v0.7.0 Highlights

• Dynamic tool surface reduction: scope-aware tool filtering — clients only see tools they're authorized to use
• DLP content sanitization: regex-based middleware redacts PII, API keys, and credentials from tool responses (--enable-dlp)
• AI-native tools: get_file_schema extracts CSV/JSON structure; summarize_file returns compact head/tail previews
• ETag concurrency control: SHA-256 content-addressable ETags with expected_etag conflict detection on edit_file and patch_file
• patch_file macro tool: atomic read-diff-write in a single tool call — supports unified diffs and line-range replacements

v0.6.0 Highlights

• Cloud-native tools: presigned URLs, object metadata/tags, version history, version restore
• Byte-range reads: read_file_chunk fetches specific byte ranges without downloading the full object
• Structured audit logging: tool invocation audit trail with pluggable sinks (stderr, file)
• Multi-provider routing: MultiProvider serves S3 + Azure + GCS from a single server instance
• Azure Managed Identity: DefaultAzureCredential for OIDC and federated auth
• Connection health-check: startup credential validation with diagnostic reporting
• MCP Resources: browse cloud storage as native MCP Resources (no tool calls needed)
• Structured errors: CloudError with typed codes and provider-specific error mappers

v0.5.0 Highlights

• Interactive TUI (cloud-fs): Terminal shell with cd, tab completion, and command history
• Multi-transport: STDIO (default), Streamable HTTP, and WebSocket
• Dual runtime: Bun-native and Node.js support (HTTP transport + SQLite provider)
• OAuth 2.1: Built-in auth server or external IdP token validation
• ext-auth extensions: Client Credentials (M2M) and Enterprise-Managed Authorization (SSO)
• Production hardening: Rate limiting, CORS, security headers, health checks, structured logging
• AI agent skill: Installable skills/cloud-fs for Claude Code, Gemini CLI, and other AI assistants

---

Quick start

Local (STDIO — default)

npx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket

Remote (HTTP)

# Bun (zero Express dependency)
bunx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport http --port 3000

# Node.js (requires express peer dep)
npx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport http --port 3000

Remote (WebSocket — Bun only)

bunx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport ws --port 3000

Demo (no cloud credentials needed)

bunx @nogoo9/mcp-server-cloud-fs memory mem://demo --enable-shell --seed-demo

---

Interactive Shell (cloud-fs)

Drop into an interactive terminal for exploring and managing cloud storage — no MCP client needed:

# S3
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs s3 s3://my-bucket

# In-memory demo with sample files
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs memory mem://demo --seed-demo

# With a config file (cloud-fs.json in CWD)
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs

Features

• cd navigation — cd data, cd .., cd / with dynamic prompt showing current directory
• Tab completion — context-aware path and command completion
• Command history — persistent across sessions (~/.cloud-fs_history)
• Relative paths — all commands resolve relative to cwd, just like a real shell
• 19 built-in commands — ls, cat, head, tail, cp, mv, rm, mkdir, touch, stat, find, grep, wc, du, echo, tee, diff, jq, cd
• Pipes & redirects — cat config.json | jq '.database', echo hello > file.txt

Local development

bun src/cli-tui.ts memory mem://demo --seed-demo

---

Transports

The server supports three MCP transports, selected via --transport:

Transport	Flag	Runtime	Use case
STDIO	--transport stdio (default)	Bun, Node	Local npx, Claude Desktop, Claude Code
Streamable HTTP	--transport http	Bun ✅, Node ✅	Remote deployment, multi-user, enterprise
WebSocket	--transport ws	Bun only	Low-latency bidirectional, real-time apps

Streamable HTTP

Implements the MCP Streamable HTTP specification with a single /mcp endpoint for POST (requests), GET (SSE notifications), and DELETE (session termination).

Dual runtime support:

• Bun: Uses WebStandardStreamableHTTPServerTransport with Bun.serve() directly — zero Express dependency, maximum performance.
• Node.js: Falls back to StreamableHTTPServerTransport with Express. Requires express as an optional peer dependency (npm install express).

Runtime is auto-detected at startup.

Session management:

Sessions use UUID v7 (RFC 9562) — time-ordered and K-sortable, making them ideal for logging, debugging, and database indexing. Sessions are tracked via the Mcp-Session-Id header.

Resumability:

When an EventStore is configured, clients can reconnect and resume receiving messages from where they left off via the Last-Event-ID SSE header.

# Basic HTTP server
cloud-fs-mcp s3 s3://my-bucket --transport http --port 3000

# With authentication
cloud-fs-mcp s3 s3://my-bucket --transport http --port 3000 --auth builtin --auth-issuer https://my-server.example.com

# Production deployment
cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 --host 0.0.0.0 \
  --auth external --auth-jwks-uri https://login.example.com/.well-known/jwks.json \
  --cors-origin https://app.example.com \
  --rate-limit 60 --rate-limit-burst 10 \
  --security-headers \
  --request-logging

WebSocket

Bun-native WebSocket transport using Bun.serve() with WebSocket upgrade handling. Provides lower latency than HTTP for high-frequency tool invocations.

• JSON-RPC message framing over WebSocket
• UUID v7 session assigned on upgrade
• WS ping/pong heartbeat for connection liveness

cloud-fs-mcp s3 s3://my-bucket --transport ws --port 3000

---

Authentication & Authorization

Authentication is disabled by default and only applies to HTTP/WS transports. STDIO mode never requires auth.

Auth modes

Mode	Flag	Description
none	--auth none (default)	No authentication. Suitable for local/trusted networks.
builtin	--auth builtin	Self-hosted OAuth 2.1 Authorization Server. The MCP server acts as both AS and RS.
external	--auth external	Validate bearer tokens against an external IdP (Okta, Auth0, Keycloak, Azure AD).

Built-in OAuth server (--auth builtin)

The server runs a full OAuth 2.1 Authorization Server using the MCP SDK's mcpAuthRouter():

• Authorization Code + PKCE (mandatory) — interactive user consent flow
• Dynamic Client Registration — MCP clients auto-register on first connect
• Refresh token rotation — single-use refresh tokens prevent replay
• Metadata discovery — /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728)

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com

External IdP (--auth external)

The server only validates bearer tokens — it does not issue tokens. Use this when you have an existing identity provider.

• JWKS validation — fetches and caches signing keys from your IdP
• JWT verification — checks signature, issuer, audience, expiry
• Token introspection — fallback for opaque tokens

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth external \
  --auth-jwks-uri https://login.example.com/.well-known/jwks.json \
  --auth-audience https://cloud-fs.example.com

ext-auth: Client Credentials (M2M)

Implements the MCP Client Credentials extension for machine-to-machine authentication without user interaction. Designed for CI/CD pipelines, background services, and automated workflows.

• JWT assertion auth (private_key_jwt per RFC 7523) — recommended
• Client secret auth (client_secret_basic) — simpler but less secure
• No user interaction required — tokens granted based on pre-registered client credentials

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com \
  --auth-client-credentials

ext-auth: Enterprise-Managed Authorization (SSO)

Implements the MCP Enterprise-Managed Authorization extension for seamless SSO via your organization's Identity Provider.

How it works:

1. User logs in to the MCP Client via the enterprise IdP (OpenID Connect or SAML)
2. Client exchanges the ID Token for an Identity Assertion JWT Authorization Grant (ID-JAG) via Token Exchange (RFC 8693)
3. Client presents the ID-JAG to this server's Authorization Server (RFC 7523)
4. Server validates the ID-JAG and issues an access token

Benefits:

• Zero manual authorization per MCP Server — SSO handles everything
• Enterprise admins control which users/groups can access which MCP servers
• Granular scope enforcement via IdP policies

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com \
  --auth-enterprise-idp https://acme.okta.com

OAuth Scopes

When auth is enabled, tool access is controlled by granular scopes:

Scope	Tools
cloud-fs:read	read_file, read_text_file, read_media_file, read_multiple_files, read_file_range, read_file_chunk, get_presigned_url, get_object_metadata, list_versions, get_file_schema, summarize_file
cloud-fs:write	write_file, edit_file, create_directory, set_object_tags, restore_version, patch_file
cloud-fs:delete	delete_file
cloud-fs:search	search_files, grep_file, grep_files, list_directory, list_directory_with_sizes, directory_tree, search_by_tag
cloud-fs:shell	shell
cloud-fs:admin	All tools + get_file_info, list_allowed_directories

When grantedScopes is set (via OAuth tokens), tools outside the granted scopes are not registered — they don't appear in tools/list at all, reducing LLM prompt token waste and preventing tool hallucination.

Tokens with insufficient scopes receive a clear error response indicating which scope is required.

---

Production Features

Health Checks

HTTP/WS transports expose Kubernetes-convention health endpoints:

Endpoint	Purpose	Success	Failure
/healthz	Liveness — is the process alive?	200 OK always	Process is dead
/readyz	Readiness — can it serve traffic?	200 OK after VFS hydration	503 during startup

Configure your orchestrator's liveness and readiness probes to use these endpoints.

Rate Limiting

Token bucket rate limiting protects against abuse. Disabled by default.

• In-memory — per-IP/per-client counters for single-process deployments
• Redis — distributed rate limiting for multi-instance deployments (uses existing optional ioredis peer dep)
• Returns 429 Too Many Requests with Retry-After header when limits are exceeded

# 60 requests/minute with burst of 10
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --rate-limit 60 --rate-limit-burst 10

CORS

Cross-Origin Resource Sharing for browser-based MCP clients:

• Strict origin allowlist — no wildcards in production
• Exposes Mcp-Session-Id and Mcp-Protocol-Version headers
• Localhost auto-allows * when --host 127.0.0.1 (dev convenience)

cloud-fs-mcp s3 s3://my-bucket --transport http \
  --cors-origin https://app.example.com \
  --cors-origin https://staging.example.com

Structured Request Logging

JSON audit trail to stderr for compliance and debugging:

{"ts":"2026-05-12T12:00:00Z","sessionId":"019...","tool":"read_file","user":"alice@example.com","latencyMs":42,"status":200}

Enable with --request-logging.

DNS Rebinding Protection

Automatically applied when binding to localhost addresses. Validates the Host header against allowed hostnames to prevent DNS rebinding attacks.

Security Headers

Opt-in HTTP response hardening via nosecone — a framework-agnostic security headers library. Works with both Bun-native and Node/Express transports.

When enabled, every HTTP response includes standard security headers:

• Content-Security-Policy
• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options
• Cross-Origin-Opener-Policy
• Cross-Origin-Resource-Policy
• Referrer-Policy
• And more (see nosecone defaults)

# Enable with defaults
cloud-fs-mcp s3 s3://my-bucket --transport http --security-headers

# Custom configuration via inline JSON
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --security-headers-config '{"contentSecurityPolicy":false}'

# Custom configuration via file
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --security-headers-config-file ./nosecone.json

Note: Requires the nosecone peer dependency: npm install nosecone

---

CLI Reference

cloud-fs-mcp <provider> <root-uri> [root-uri...] [options]

Providers

Provider	URI format	Description
s3	s3://bucket[/prefix]	AWS S3, and any S3-compatible endpoint (MinIO, RustFS, Cloudflare R2, Backblaze B2, Wasabi, LocalStack, …)
azure	az://container[/prefix]	Azure Blob Storage
gcs	gs://bucket[/prefix]	Google Cloud Storage
memory	mem://name	In-memory (ephemeral, for demos)
sqlite	sqlite://name	SQLite (persistent local)

Options

Transport & Network

Flag	Default	Description
--transport <stdio|http|ws>	stdio	Transport protocol
--port <number>	3000	Listen port (http/ws only)
--host <address>	127.0.0.1	Bind address (http/ws only)

Authentication

Flag	Default	Description
--auth <none|builtin|external>	none	Auth mode (http/ws only)
--auth-issuer <url>	—	OAuth issuer URL (builtin mode)
--auth-jwks-uri <url>	—	JWKS URI (external mode)
--auth-audience <string>	—	Expected token audience (external mode)
--auth-client-credentials	false	Enable Client Credentials ext-auth flow
--auth-enterprise-idp <url>	—	Enable Enterprise-Managed Authorization

Production

Flag	Default	Description
--cors-origin <origin>	—	Allowed CORS origin (repeatable)
--rate-limit <req/min>	0 (off)	Rate limit per client
--rate-limit-burst <n>	10	Burst allowance
--request-logging	false	Enable structured JSON request logging
--audit-log	false	Enable tool invocation audit logging to stderr
--audit-log-file <path>	—	Write audit log to file (implies --audit-log)
--security-headers	false	Enable security headers via nosecone
--security-headers-config <json>	—	Inline JSON config for nosecone
--security-headers-config-file <path>	—	Load nosecone config from a JSON file

Storage & Cache

Flag	Default	Description
--region <region>	—	Cloud region (S3, GCS)
--endpoint <url>	—	Custom endpoint for S3-compatible backends
--cache-store <memory|fs|redis>	memory	Cache backend
--cache-ttl <seconds>	60	Cache TTL in seconds
--sync-debounce <ms>	2000	Write flush delay in ms
--cache-dir <path>	—	Directory for fs cache store
--no-cache	—	Bypass cache entirely (pass-through mode)
--gcs-endpoint <url>	—	Custom endpoint for GCS
--sqlite-db <path>	—	SQLite database file path
--ca-file <path>	—	PEM CA bundle for TLS (S3-compatible + Redis)

Tools

Flag	Default	Description
--enable-delete	false	Enable the delete_file tool
--enable-shell	false	Enable the shell tool
--enable-dlp	false	Enable DLP content sanitization (redacts PII/secrets from responses)
--grep-max-objects <n>	1000	Max objects grep_files scans per call
--seed-demo	false	Seed VFS with sample files for demo

Credentials are always sourced from SDK credential chains — never CLI flags.

---

Provider Setup

AWS S3

Credentials are read from the standard AWS credential chain: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars, ~/.aws/credentials, EC2 instance profiles, and so on.

cloud-fs-mcp s3 s3://my-bucket --region us-east-1

S3-compatible storage

Any S3-compatible backend works via --endpoint. All use the standard AWS credential chain (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY).

Provider	--endpoint value	Notes
MinIO	http://minio:9000	Self-hosted; use --ca-file for TLS with a private CA
RustFS	http://rustfs:9000	Rust-native S3-compatible store
LocalStack	http://localhost:4566	Full AWS emulator for local dev and CI
Cloudflare R2	https://<account-id>.r2.cloudflarestorage.com	No egress fees; use an R2 API token as the secret key
Backblaze B2	https://s3.<region>.backblazeb2.com	Use B2 application key ID / key
Wasabi	https://s3.<region>.wasabisys.com	Compatible, no egress fees
DigitalOcean Spaces	https://<region>.digitaloceanspaces.com	Use a Spaces access key
Scaleway	https://s3.<region>.scw.cloud	Use a Scaleway access key
Ceph RGW	http://<rgw-host>:<port>	Enterprise self-hosted; supports all S3 APIs
SeaweedFS	http://<master>:8333	High-throughput distributed FS with S3 API
Garage	http://<node>:3900	Lightweight distributed S3 for homelabs

# MinIO
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
cloud-fs-mcp s3 s3://my-bucket --endpoint http://minio:9000

# Cloudflare R2
export AWS_ACCESS_KEY_ID=<r2-access-key-id>
export AWS_SECRET_ACCESS_KEY=<r2-secret-access-key>
cloud-fs-mcp s3 s3://my-bucket --endpoint https://<account-id>.r2.cloudflarestorage.com --region auto

# Backblaze B2
export AWS_ACCESS_KEY_ID=<b2-key-id>
export AWS_SECRET_ACCESS_KEY=<b2-application-key>
cloud-fs-mcp s3 s3://my-bucket --endpoint https://s3.us-west-004.backblazeb2.com --region us-west-004

# LocalStack
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
cloud-fs-mcp s3 s3://my-bucket --endpoint http://localhost:4566 --region us-east-1

TLS with private CA: For MinIO, RustFS, or Ceph with a self-signed certificate, add --ca-file /path/to/ca.pem.

Azure Blob Storage

Uses DefaultAzureCredential — works with AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET env vars, managed identity, az login, and so on.

cloud-fs-mcp azure az://my-container

Google Cloud Storage

Uses Application Default Credentials (ADC). Set GOOGLE_APPLICATION_CREDENTIALS or run gcloud auth application-default login.

cloud-fs-mcp gcs gs://my-bucket

In-Memory (ephemeral)

Zero-config, zero-dependency provider. All data lives in a Map and is lost when the process exits.

cloud-fs-mcp memory mem://demo --enable-shell

SQLite (persistent local)

Persistent local storage using WAL mode. Dual-runtime: uses bun:sqlite on Bun, better-sqlite3 on Node.js (install as peer dep: npm install better-sqlite3).

cloud-fs-mcp sqlite sqlite://my-bucket --sqlite-db /tmp/cloud-fs.db --enable-shell

---

MCP Client Config

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cloud-fs": {
      "command": "npx",
      "args": ["-y", "@nogoo9/mcp-server-cloud-fs", "s3", "s3://my-bucket"]
    }
  }
}

Claude Code

.mcp.json in your project root:

{
  "mcpServers": {
    "cloud-fs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nogoo9/mcp-server-cloud-fs", "s3", "s3://my-bucket"]
    }
  }
}

Remote HTTP client

{
  "mcpServers": {
    "cloud-fs": {
      "type": "streamable-http",
      "url": "https://cloud-fs.example.com/mcp"
    }
  }
}

---

Tool Reference

All paths are cloud URIs — e.g. s3://my-bucket/path/to/file.txt. The server validates every path against the configured root URIs at startup; requests outside allowed roots are rejected.

Read tools

Tool	Parameters	Description
read_file	path	Read a file. Binary → base64; text → UTF-8.
read_text_file	path, head?, tail?	Read text file with optional head/tail line limits.
read_media_file	path	Read image/media as base64 MCP image content block.
read_multiple_files	paths	Read several files in parallel.
read_file_range ✨	path, offset, limit	Read a 1-based line range with total line count header.
read_file_chunk ✨	path, start_byte, end_byte?, encoding?	Read a byte range without downloading the entire file. Max 10MB.

Write tools

Tool	Parameters	Description
write_file	path, content	Write/overwrite a file. Flushed after debounce window.
edit_file	path, edits[], dryRun?, expected_etag?	Apply { oldText, newText } edits. Preview with dryRun. Optional ETag conflict detection.

Directory tools

Tool	Parameters	Description
create_directory	path	Create a directory placeholder and parent prefixes.
list_directory	path	List immediate children (like ls).
list_directory_with_sizes	path, sortBy?, limit?	List children with sizes. Sort by size or name.
directory_tree	path, excludePatterns?	Recursive directory tree with glob exclusions.

Move, Copy & Delete tools

Tool	Parameters	Description
move_file	source, destination	Move file. Server-side copy + delete for same-bucket.
copy_file ✨	source, destination	Copy file. Server-side for same-bucket.
delete_file ✨	path	Delete file. Requires --enable-delete.

Search tools

Tool	Parameters	Description
search_files	path, pattern, excludePatterns?	Glob-based object key search.
grep_file ✨	path, pattern, case_insensitive?	Regex search in a single file with line numbers.
grep_files ✨	path, pattern, glob?, case_insensitive?, output_mode?, max_objects?	Regex search across all objects under a path.

Info tools

Tool	Parameters	Description
get_file_info	path	File metadata: size, last-modified, content type.
list_allowed_directories	(none)	List configured root URIs.

✨ = Extended tool

Cloud-native tools ☁️

Tool	Parameters	Description
get_presigned_url ☁️	path, operation?, expires_in?	Generate a temporary access URL (default: GET, 1 hour).
get_object_metadata ☁️	path	Size, content type, last modified, custom metadata, and tags.
set_object_tags ☁️	path, tags	Replace object tags with key-value pairs.
search_by_tag ☁️	path, tags, recursive?	Find objects matching tag filters (AND logic).
list_versions ☁️	path, max_results?, page_token?	Version history with timestamps, sizes, and markers.
restore_version ☁️	path, version_id	Restore a previous object version (copies over current).

☁️ = Cloud-native tool (requires provider support)

AI-native tools 🧠

Tool	Parameters	Description
get_file_schema 🧠	path	Extract structural schema: CSV column names/types/samples, JSON shape, or text line/byte counts.
summarize_file 🧠	path, max_lines?	Compact head/tail preview with file size, line count, and content type.

🧠 = AI-native tool (reduces LLM context token waste)

Macro tools 🩹

Tool	Parameters	Description
patch_file 🩹	path, patch, format?, expected_etag?	Apply unified diffs or line-range replacements atomically in a single tool call.

🩹 = Macro tool (combines read + transform + write)

Shell tool ⚡

Tool	Parameters	Description
shell ⚡	command	Execute POSIX-like commands. Supports pipes, redirects. Requires --enable-shell.

Built-in commands: ls, cat, head, tail, cp, mv, rm, mkdir, touch, stat, find, grep, wc, du, echo, tee, diff, jq, cd

Relative paths

All shell commands (and all other tools) support relative paths — you don't need to type the full URI every time. Paths without a scheme prefix (s3://, mem://, etc.) are resolved relative to the first configured root:

# With root s3://my-bucket/data, these are equivalent:
shell "cat config.json"
shell "cat s3://my-bucket/data/config.json"

# Subdirectories work naturally:
shell "ls logs/"
shell "cat logs/app.log | grep ERROR"

# ls with no args lists the root's contents:
shell "ls"

# find with no args searches from the root:
shell "find -name '*.json'"

Standard . and .. are normalized, with .. traversal blocked at the root boundary for security.

Examples

# List root contents
shell "ls -l"

# JSON query with jq
shell "cat config.json | jq '.database.port'"

# Search and count
shell "grep -i error server.log | wc -l"

# Write files
shell "echo hello world > greeting.txt"

# Copy and diff
shell "cp config.json config.backup.json"
shell "diff config.json config.backup.json"

# Full URIs still work for cross-root access
shell "cat s3://other-bucket/file.txt"

⚡ Requires --enable-shell. rm and mv additionally require --enable-delete.

---

Architecture: Virtual Filesystem (VFS)

All tool operations are mediated through a Virtual Filesystem (VFS) layer inspired by FUSE.

┌─────────────────────────────────────────────────────────┐
│  MCP Tool Handlers (read, write, list, stat, …)         │
├─────────────────────────────────────────────────────────┤
│  VirtualFS                                              │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐              │
│  │  Inodes   │ │ DirIndex  │ │ Tombstones│              │
│  │ (metadata)│ │ (parents) │ │ (deleted) │              │
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘              │
│        └──────────────┴─────────────┘                   │
│         ⇣ Overlay (in-memory, persisted to CacheStore)  │
├─────────────────────────────────────────────────────────┤
│  CacheStore (Memory / Filesystem / Redis)               │
├─────────────────────────────────────────────────────────┤
│  StorageProvider (S3 / Azure Blob / GCS / Memory / SQL) │
└─────────────────────────────────────────────────────────┘

Operation	Resolution
get()	Cache hit → return. Tombstoned → throw. Else → provider fallback.
stat()	Inode overlay → cached content size → provider headObject.
list()	Provider listing – tombstones + overlay dirIndex entries.
put()	Cache set + markDirty + inode update + dirIndex. Immediate visibility.
remove()	Provider deleteObject + cache evict + tombstone. Immediate invisibility.

VFS metadata is persisted to the CacheStore under __vfs__/* keys. On startup, VirtualFS.hydrate() restores state; corrupted data is silently discarded.

---

Caching

Backend	Flag	Notes
Memory (default)	--cache-store memory	In-process, fast, not shared, not persistent.
Filesystem	--cache-store fs --cache-dir <path>	Survives restarts.
Redis	--cache-store redis	Shared, persistent. Requires ioredis peer dep. REDIS_URL env var. Use rediss:// for TLS.

Writes land in cache immediately (marked dirty), flushed after debounce window (default: 2s). Graceful shutdown flushes all dirty entries before exit. Pass-through mode (--no-cache) sends every operation directly to the provider.

⚠️ Redis TLS: The server warns at startup when REDIS_URL uses unencrypted redis://. Use rediss:// for TLS-encrypted connections in production.

Custom CA Certificates

Use --ca-file <path> to supply a PEM CA bundle for S3-compatible endpoints (MinIO, RustFS) and Redis running with a private CA:

# S3-compatible with self-signed CA
cloud-fs-mcp s3 s3://my-bucket \
  --endpoint https://minio.internal:9000 \
  --ca-file /etc/ssl/certs/my-ca.pem

# Redis with private CA
REDIS_URL=rediss://redis.internal:6380 \
cloud-fs-mcp s3 s3://my-bucket --cache-store redis \
  --ca-file /etc/ssl/certs/my-ca.pem

For runtime-wide CA trust (all providers + Redis), use the standard NODE_EXTRA_CA_CERTS env var instead:

NODE_EXTRA_CA_CERTS=/etc/ssl/certs/my-ca.pem cloud-fs-mcp s3 s3://my-bucket

---

Programmatic Usage (npm library)

import {
  createMcpServer, VirtualFS, MemoryStore,
  S3Provider, parseUri,
} from "@nogoo9/mcp-server-cloud-fs";

const roots    = [parseUri("s3://my-bucket")];
const provider = new S3Provider({ region: "us-east-1" });
const cache    = new MemoryStore(provider, { ttlMs: 60_000, syncDebounceMs: 2000 });
const vfs      = new VirtualFS(provider, cache);
await vfs.hydrate();

const server = createMcpServer({ vfs, roots });

Exported API

Export	Description
createMcpServer(ctx)	Create a configured MCP server instance
executeShell(command, ctx)	Run POSIX-like commands against the VFS
VirtualFS	FUSE-inspired write-back overlay
MemoryStore, FilesystemStore, createRedisStore, PassThroughCache	Cache backends
S3Provider, AzureProvider, GcsProvider, MemoryProvider, SqliteProvider, MultiProvider	Storage providers
CloudError, CloudErrorCode	Structured cloud-aware error handling
checkHealth, formatHealthReport	Connection health-check utilities
AuditLogger, StderrAuditSink, FileAuditSink	Tool invocation audit logging
parseUri, toCacheKey, resolveToolPath	Path utilities
ShellContext, ShellCommandHandler	Shell extension types

---

MCP Inspector

# Quick demo (no credentials needed)
bun run inspect:memory

# Custom configuration
bun run inspect -- s3 s3://my-bucket --region us-east-1 --enable-shell

---

MCP App: Interactive Shell (xterm.js)

Build the app: bun run build:app → outputs dist/app/shell-app.html.

Catppuccin Mocha theme, command history, auto-resize. Renders inside compatible MCP hosts (Claude Desktop) via the MCP Apps extension.

---

Development & Testing

See CONTRIBUTING.md for full setup instructions.

AI agent skills are installed separately after cloning via bun x skills add semgrep/skills — see CONTRIBUTING.md for details.

Test tiers

Tier	Command	Infra?
Unit	bun run test	No
E2E (HTTP)	bun run test:e2e:http	No
E2E (Infra)	bun run test:e2e:infra	Docker
Integration	bun run test:integration	Docker
All	bun run test:all	Docker

CI pipeline

The CI workflow runs on every push/PR:

1. ci job: lint → typecheck → unit tests (with coverage) → HTTP E2E → build
2. e2e job: full E2E with Docker Compose (MinIO, Redis)

HTTP E2E tests use the in-memory provider and need zero infrastructure, making them fast and reliable for every CI run.

---

AI Agent Skill

The skills/cloud-fs directory contains an installable AI agent skill that teaches coding assistants (Claude Code, Gemini CLI, etc.) how to use cloud-fs as a POSIX-like virtual filesystem. Install it to give your assistant fluency with cloud storage commands.

What it provides

• MCP mode auto-detection — recognizes mcp__cloud-fs__* tools and maps user intents to the right tool calls
• Bootstrap flow — walks the user through first-time setup when the MCP server isn't configured yet
• POSIX-to-MCP mapping — translates shell commands (ls, cat, grep, find, cp, etc.) into the correct MCP tool calls
• Provider credential reference — AWS, Azure, GCS, MinIO/RustFS, SQLite setup guidance
• .mcp.json persistence — offers to save provider configuration so future sessions are pre-wired

Installation

# Claude Code
claude mcp add-skill nogoo9/mcp-server-cloud-fs

# skills.sh
npx skills add nogoo9/mcp-server-cloud-fs

# or with bun instead
bun x skills add nogoo9/mcp-server-cloud-fs

See CONTRIBUTING.md for details on the skill system.

---

Documentation

Full documentation is available at nogoo9.github.io/mcp-server-cloud-fs.

• 📖 Versioned docs for each release (v0.4.0+)
• 🔄 PR preview docs for open pull requests
• 🔍 Full-text search, dark mode, responsive design
• Built with VitePress

To run the documentation site locally:

bun run docs:dev      # start dev server at http://localhost:5173
bun run docs:build    # build static site
bun run docs:preview  # preview production build

---

License

PolyForm Shield 1.0.0. Free for any non-competitive use.

---

Built with