MCP Server Cloud Fs

@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:

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

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,