mcp-server-cloud-fs

<p align="center"> <img src="docs/public/images/logo.png" alt="nogoo9" width="128" /> </p> <h1 align="center">@nogoo9/mcp-server-cloud-fs</h1> <p align="center"> <a href="https://github.com/nogoo9/mcp-server-cloud-fs/actions/workflows/ci.yml"><img src="https://github.com/nogoo9/mcp-server-cloud-fs/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://nogoo9.github.io/mcp-server-cloud-fs/"><img src="https://img.shields.io/badge/docs-GitHub_Pages-blue?logo=github" alt="Docs"></a> <a href="https://coveralls.io/github/nogoo9/mcp-server-cloud-fs?branch=main"><img src="https://coveralls.io/repos/github/nogoo9/mcp-server-cloud-fs/badge.svg?branch=main" alt="Coverage"></a> <a href="https://semgrep.dev"><img src="https://img.shields.io/badge/SAST-Semgrep-4B11A8?logo=semgrep&logoColor=white" alt="Semgrep"></a> <br/> <a href="https://www.npmjs.com/package/@nogoo9/mcp-server-cloud-fs"><img src="https://img.shields.io/npm/v/@nogoo9/mcp-server-cloud-fs" alt="npm"></a> <img src="https://img.shields.io/npm/dm/%40nogoo9%2Fmcp-server-cloud-fs" alt="NPM Downloads"> <a href="https://skills.sh/nogoo9/mcp-server-cloud-fs"><img src="https://skills.sh/b/nogoo9/mcp-server-cloud-fs" alt="skills.sh"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm--Shield--1.0.0-blue" alt="License"></a> </p> <p align="center"> Cloud replacement for <code>mcp-server-filesystem</code> — 30 tools for S3, Azure Blob, and GCS.<br/> Deploy locally via STDIO or remotely over HTTP/WebSocket with OAuth 2.1 auth.<br/> Also available as an npm library and interactive TUI. </p> <p align="center"> <strong>📖 <a href="https://nogoo9.github.io/mcp-server-cloud-fs/latest/">Read the full documentation →</a></strong> </p> <p align="center"> <a href="https://buymeacoffee.com/eterna2"> <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="48"> </a> </p>

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,