mcp-server-cloud-fs

@nogoo9/mcp-server-cloud-fs

mcp-server-filesystemのクラウド代替：S3、Azure Blob、GCS 向けの30個のツールを提供します。
STDIO 経由でローカルにデプロイするか、OAuth 2.1 認証を使用して HTTP/WebSocket 経由でリモートにデプロイできます。
npm ライブラリおよびインタラクティブ TUI としても利用できます。

📖 ドキュメント全文を読む →

プロバイダー： Amazon S3 · Azure Blob Storage · Google Cloud Storage · MinIO · RustFS · Cloudflare R2 · Backblaze B2 · Wasabi · LocalStack · SQLite · In-Memory

---

目次

• 機能
• クイックスタート
• インタラクティブシェル
• トランスポート
• 認証と認可
• 本番環境向け機能
• CLI リファレンス
• プロバイダーのセットアップ
• MCP クライアントの設定
• ツールリファレンス
• アーキテクチャ：VFS
• キャッシュ
• プログラムからの使用方法
• MCP Inspector
• 開発とテスト
• AI エージェントのスキル
• ドキュメント
• ライセンス

---

機能

@nogoo9/mcp-server-cloud-fs は、mcp-server-filesystem で定義されている14個のツールすべてを、同じツール名、同じパラメータスキーマでクラウドオブジェクトストレージ経由で提供します。現在 mcp-server-filesystem を指定している任意の MCP クライアント設定に追加すれば、AI アシスタントが S3、Azure Blob Storage、または Google Cloud Storage のバケットに対する読み書きアクセスを利用できるようになります。

また、claude-codeのファイルシステムツールに着想を得た5つの拡張ツールも含まれています。行範囲の読み取り、バイト範囲チャンクの読み取り、プロセス内の正規表現検索（単一ファイルと複数ファイル）、サーバーサイドコピー、オプトイン方式の削除に対応します。さらに、6つのクラウドネイティブツール（署名付きURL、オブジェクトのメタデータ／タグ、タグベースの検索、バージョン履歴、バージョンの復元）、2つのAIネイティブツール（スキーマ抽出、ファイル要約）、1つのマクロツール（アトミックな差分を適用する patch_file）も含まれています。

仮想ファイルシステム（VFS）レイヤーは、ETagベースの同時実行制御を備えたFUSEのようなキャッシュ一貫性を提供します。また、シェルツールを使って、クラウドストレージに対してPOSIX風のコマンド（ls、grep、jq、cat | wc など）を実行でき、パッケージはプログラムから利用できるnpmライブラリとしても提供されています。

v0.7.0の主な変更点

• ツールサーフェスの動的な縮小：スコープを考慮したツールのフィルタリングにより、クライアントには利用を許可されたツールのみが表示されます
• DLPによるコンテンツのサニタイズ：正規表現ベースのミドルウェアがツールのレスポンスからPII、APIキー、認証情報を秘匿化します（--enable-dlp）
• AIネイティブツール：get_file_schema はCSV／JSONの構造を抽出し、summarize_file はコンパクトな先頭／末尾のプレビューを返します
• ETagによる同時実行制御：SHA-256コンテンツアドレス方式のETagと、edit_file および patch_file における expected_etag の競合検出
• patch_file マクロツール：1回のツール呼び出しでアトミックな読み取り・差分適用・書き込みを実行します。統合差分と行範囲の置換に対応します

v0.6.0の主な変更点

• クラウドネイティブツール：署名付きURL、オブジェクトのメタデータ／タグ、バージョン履歴、バージョンの復元
• バイト範囲読み取り：read_file_chunk はオブジェクト全体をダウンロードせず、特定のバイト範囲を取得します
• 構造化監査ログ：プラグイン可能な出力先（stderr、ファイル）に対応したツール呼び出しの監査証跡
• マルチプロバイダールーティング：MultiProvider により、単一のサーバーインスタンスからS3、Azure、GCSを提供します
• Azure Managed Identity：OIDCおよびフェデレーション認証に対応する DefaultAzureCredential
• 接続ヘルスチェック：診断レポート付きの起動時認証情報検証
• MCPリソース：ツール呼び出しを使わずに、ネイティブのMCPリソースとしてクラウドストレージを閲覧できます
• 構造化エラー：型付きコードとプロバイダー固有のエラーマッパーを備えた CloudError

v0.5.0の主な変更点

• 対話型TUI（cloud-fs）：cd、タブ補完、コマンド履歴に対応したターミナルシェル
• マルチトランスポート：STDIO（デフォルト）、Streamable HTTP、WebSocket
• デュアルランタイム：BunネイティブおよびNode.jsに対応（HTTPトランスポート＋SQLiteプロバイダー）
• OAuth 2.1：組み込み認証サーバー、または外部IdPのトークン検証
• ext-auth拡張機能：クライアント認証情報（M2M）およびエンタープライズ管理認可（SSO）
• 本番環境向けの強化：レート制限、CORS、セキュリティヘッダー、ヘルスチェック、構造化ログ
• AIエージェントスキル：Claude Code、Gemini CLI、その他のAIアシスタント向けにインストール可能な skills/cloud-fs

---

クイックスタート

ローカル（STDIO — デフォルト）

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

リモート（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

リモート（WebSocket — Bunのみ）

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

デモ（クラウドの認証情報は不要）

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

---

対話型シェル（cloud-fs）

MCPクライアントを使わずに、クラウドストレージを調べて管理できる対話型ターミナルを起動します：

# 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

機能

• cd による移動 — cd data、cd ..、cd / に対応し、現在のディレクトリを動的にプロンプトへ表示します
• タブ補完 — コンテキストに応じたパスとコマンドの補完
• コマンド履歴 — セッションをまたいで保持されます（~/.cloud-fs_history）
• 相対パス — すべてのコマンドが実際のシェルと同様に cwd を基準に解決されます
• 19 個の組み込みコマンド — ls、cat、head、tail、cp、mv、rm、mkdir、touch、stat、find、grep、wc、du、echo、tee、diff、jq、cd
• パイプとリダイレクト — cat config.json | jq '.database'、echo hello > file.txt

ローカル開発

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

---

トランスポート

サーバーは 3 種類の MCP トランスポートをサポートしており、--transport で選択できます。

トランスポート	フラグ	ランタイム	用途
STDIO	--transport stdio（デフォルト）	Bun、Node	ローカルの npx、Claude Desktop、Claude Code
Streamable HTTP	--transport http	Bun ✅、Node ✅	リモートへのデプロイ、複数ユーザー、エンタープライズ
WebSocket	--transport ws	Bun のみ	低遅延の双方向通信、リアルタイムアプリ

Streamable HTTP

POST（リクエスト）、GET（SSE 通知）、DELETE（セッション終了）に対応する単一の /mcp エンドポイントを使用し、MCP Streamable HTTP 仕様を実装しています。

2 種類のランタイムをサポート：

• Bun：Bun.serve() と WebStandardStreamableHTTPServerTransport を直接使用します。Express への依存がなく、高いパフォーマンスを実現します。
• Node.js：Express と StreamableHTTPServerTransport にフォールバックします。オプションのピア依存関係として express が必要です（npm install express）。

ランタイムは起動時に自動検出されます。

セッション管理：

セッションには UUID v7（RFC 9562）を使用します。時刻順かつ K-sortable であり、ログ記録、デバッグ、データベースのインデックス作成に適しています。セッションは Mcp-Session-Id ヘッダーで追跡されます。

再開機能：

EventStore が設定されている場合、クライアントは Last-Event-ID SSE ヘッダーを使って再接続し、中断した箇所からメッセージの受信を再開できます。

# 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.serve() と WebSocket アップグレード処理を使用する、Bun ネイティブの WebSocket トランスポートです。高頻度でツールを呼び出す場合、HTTP より低い遅延を実現します。

• WebSocket 上の JSON-RPC メッセージフレーミング
• アップグレード時に UUID v7 セッションを割り当て
• 接続の生存確認に WS ping/pong ハートビートを使用

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

---

認証と認可

認証はデフォルトで無効であり、HTTP/WS トランスポートにのみ適用されます。STDIO モードでは認証は必要ありません。

認証モード

モード	フラグ	説明
none	--auth none（デフォルト）	認証なし。ローカルまたは信頼できるネットワークに適しています。
builtin	--auth builtin	セルフホスト可能な OAuth 2.1 認可サーバー。MCP サーバーが AS と RS の両方として動作します。
external	--auth external	外部 IdP（Okta、Auth0、Keycloak、Azure AD）に対してベアラートークンを検証します。

組み込み OAuth サーバー（--auth builtin）

サーバーは MCP SDK の mcpAuthRouter() を使用して、完全な OAuth 2.1 認可サーバーを実行します。

• 認可コード + PKCE（必須）— 対話型のユーザー同意フロー
• 動的クライアント登録 — MCP クライアントは初回接続時に自動登録されます
• リフレッシュトークンのローテーション — 使い捨てのリフレッシュトークンでリプレイ攻撃を防止します
• メタデータの検出 — /.well-known/oauth-authorization-server（RFC 8414）および /.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

外部 IdP（--auth external）

サーバーはベアラートークンを検証するだけで、トークンは発行しません。既存の ID プロバイダーがある場合に使用します。

• JWKS 検証 — IdP から署名鍵を取得してキャッシュします
• JWT 検証 — 署名、発行者、オーディエンス、有効期限を確認します
• トークンイントロスペクション — 不透明なトークンの場合のフォールバック

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：クライアントクレデンシャル（M2M）

ユーザーとのやり取りなしでマシン間認証を行うMCP Client Credentials 拡張を実装します。CI/CD パイプライン、バックグラウンドサービス、自動化されたワークフロー向けに設計されています。

• JWT アサーション認証（RFC 7523 に準拠した private_key_jwt）— 推奨
• クライアントシークレット認証（client_secret_basic）— より簡単ですが、安全性は低くなります
• ユーザーとのやり取りは不要です — 事前登録されたクライアントクレデンシャルに基づいてトークンが付与されます

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：エンタープライズ管理認可（SSO）

組織の ID プロバイダーを介したシームレスな SSO を実現するMCP Enterprise-Managed Authorization 拡張を実装します。

仕組み：

1. ユーザーがエンタープライズ IdP（OpenID Connect または SAML）を介して MCP クライアントにログインします
2. クライアントが Token Exchange（RFC 8693）を介して ID Token を Identity Assertion JWT Authorization Grant（ID-JAG）に交換します
3. クライアントがこのサーバーの Authorization Server（RFC 7523）に ID-JAG を提示します
4. サーバーが ID-JAG を検証し、アクセストークンを発行します

メリット：

• MCP サーバーごとの手動認可は不要です — SSO がすべて処理します
• エンタープライズ管理者が、どのユーザー／グループがどの MCP サーバーにアクセスできるかを管理できます
• IdP ポリシーによるきめ細かなスコープ適用が可能です

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 スコープ

認証が有効な場合、ツールへのアクセスはきめ細かなスコープによって制御されます。

スコープ	ツール
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	すべてのツール + get_file_info、list_allowed_directories

grantedScopes が設定されている場合（OAuth トークン経由）、許可されたスコープの範囲外にあるツールは登録されません。つまり、tools/list に一切表示されないため、LLM のプロンプトトークンの無駄を減らし、ツールの幻覚を防止できます。

スコープが不足しているトークンには、必要なスコープを示す明確なエラーレスポンスが返されます。

---

本番環境向け機能

ヘルスチェック

HTTP／WS トランスポートでは、Kubernetes の慣例に沿ったヘルスチェックエンドポイントを公開します。

エンドポイント	目的	成功	失敗
/healthz	生存確認 — プロセスが稼働しているか	常に 200 OK	プロセスが停止している
/readyz	準備状態確認 — トラフィックを処理できるか	VFS のハイドレーション後に 200 OK	起動中は 503

オーケストレーターの生存プローブと準備状態プローブがこれらのエンドポイントを使用するように設定してください。

レート制限

トークンバケット方式のレート制限により、不正利用を防止します。デフォルトでは無効です。

• インメモリ — 単一プロセスのデプロイ向けに、IP／クライアントごとのカウンターを使用します
• Redis — 複数インスタンスのデプロイ向けに、分散レート制限を行います（既存のオプションの ioredis peer dep を使用します）
• 制限を超えると、Retry-After ヘッダー付きで 429 Too Many Requests を返します

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

CORS

ブラウザベースの MCP クライアント向けのクロスオリジンリソース共有です。

• 厳格なオリジン許可リスト — 本番環境ではワイルドカードを使用しません
• Mcp-Session-Id と Mcp-Protocol-Version ヘッダーを公開します
• --host 127.0.0.1 の場合、localhost では * を自動的に許可します（開発時の利便性のため）

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

構造化リクエストログ

コンプライアンス対応とデバッグのため、stderr に JSON 形式の監査証跡を出力します。

{"ts":"2026-05-12T12:00:00Z","sessionId":"019...","tool":"read_file","user":"[email protected]","latencyMs":42,"status":200}

--request-logging で有効にします。

DNS リバインディング保護

localhost アドレスにバインドする際に自動的に適用されます。DNS リバインディング攻撃を防ぐため、Host ヘッダーが許可されたホスト名と一致するか検証します。

セキュリティヘッダー

nosecone を使用した、オプトイン方式の HTTP レスポンス強化です。nosecone はフレームワークに依存しないセキュリティヘッダーライブラリです。Bun ネイティブおよび Node/Express の両方のトランスポートで動作します。

有効にすると、すべての HTTP レスポンスに標準のセキュリティヘッダーが含まれます。

• Content-Security-Policy
• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options
• Cross-Origin-Opener-Policy
• Cross-Origin-Resource-Policy
• Referrer-Policy
• その他（nosecone のデフォルト設定を参照）

# 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

注： nosecone のピア依存関係が必要です：npm install nosecone

---

CLI リファレンス

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

プロバイダー

プロバイダー	URI 形式	説明
s3	s3://bucket[/prefix]	AWS S3、および S3 互換のあらゆるエンドポイント（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	インメモリ（揮発性、デモ用）
sqlite	sqlite://name	SQLite（ローカル永続ストレージ）

オプション

トランスポートとネットワーク

フラグ	デフォルト	説明
--transport <stdio|http|ws>	stdio	トランスポートプロトコル
--port <number>	3000	リッスンポート（http/ws のみ）
--host <address>	127.0.0.1	バインドアドレス（http/ws のみ）

認証

フラグ	デフォルト	説明
--auth <none|builtin|external>	none	認証モード（http/ws のみ）
--auth-issuer <url>	—	OAuth 発行者 URL（builtin モード）
--auth-jwks-uri <url>	—	JWKS URI（external モード）
--auth-audience <string>	—	想定するトークンのオーディエンス（external モード）
--auth-client-credentials	false	Client Credentials ext-auth フローを有効化
--auth-enterprise-idp <url>	—	Enterprise-Managed Authorization を有効化

本番環境

フラグ	デフォルト	説明
--cors-origin <origin>	—	許可する CORS オリジン（複数指定可）
--rate-limit <req/min>	0（無効）	クライアントごとのレート制限
--rate-limit-burst <n>	10	バースト許容量
--request-logging	false	構造化 JSON リクエストログを有効化
--audit-log	false	ツール呼び出しの監査ログを stderr に出力
--audit-log-file <path>	—	監査ログをファイルに出力（--audit-log を自動的に有効化）
--security-headers	false	nosecone によるセキュリティヘッダーを有効化
--security-headers-config <json>	—	nosecone 用のインライン JSON 設定
--security-headers-config-file <path>	—	JSON ファイルから nosecone の設定を読み込み

ストレージとキャッシュ

フラグ	デフォルト	説明
--region <region>	—	クラウドリージョン（S3、GCS）
--endpoint <url>	—	S3 互換バックエンド用のカスタムエンドポイント
--cache-store <memory|fs|redis>	memory	キャッシュバックエンド
--cache-ttl <seconds>	60	キャッシュの TTL（秒）
--sync-debounce <ms>	2000	書き込みフラッシュの遅延時間（ミリ秒）
--cache-dir <path>	—	fs キャッシュストア用のディレクトリ
--no-cache	—	キャッシュを完全にバイパス（パススルーモード）
--gcs-endpoint <url>	—	GCS 用のカスタムエンドポイント
--sqlite-db <path>	—	SQLite データベースファイルのパス
--ca-file <path>	—	TLS 用の PEM CA バンドル（S3 互換バックエンドおよび Redis）

ツール

フラグ	デフォルト	説明
--enable-delete	false	delete_file ツールを有効化
--enable-shell	false	shell ツールを有効化
--enable-dlp	false	DLP によるコンテンツのサニタイズを有効化（レスポンス内の PII／シークレットをマスキング）
--grep-max-objects <n>	1000	1 回の呼び出しで grep_files がスキャンするオブジェクトの最大数
--seed-demo	false	デモ用のサンプルファイルで VFS を初期化

認証情報は常に SDK の認証情報チェーンから取得されます。CLI フラグから取得されることはありません。

---

プロバイダーのセットアップ

AWS S3

認証情報は標準の AWS 認証情報チェーンから読み込まれます。AWS_ACCESS_KEY_ID／AWS_SECRET_ACCESS_KEY 環境変数、~/.aws/credentials、EC2 インスタンスプロファイルなどが対象です。

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

S3 互換ストレージ

--endpoint を指定すれば、どの S3 互換バックエンドでも使用できます。いずれも標準の AWS 認証情報チェーンを使用します（AWS_ACCESS_KEY_ID／AWS_SECRET_ACCESS_KEY）。

プロバイダー	--endpoint の値	備考
MinIO	http://minio:9000	セルフホスト型です。プライベート CA を使った TLS には --ca-file を使用します
RustFS	http://rustfs:9000	Rust ネイティブの S3 互換ストレージです
LocalStack	http://localhost:4566	ローカル開発や CI 向けの完全な AWS エミュレーターです
Cloudflare R2	https://<account-id>.r2.cloudflarestorage.com	エグレス料金はかかりません。シークレットキーには R2 API トークンを使用します
Backblaze B2	https://s3.<region>.backblazeb2.com	B2 のアプリケーションキー ID／キーを使用します
Wasabi	https://s3.<region>.wasabisys.com	互換性があり、エグレス料金はかかりません
DigitalOcean Spaces	https://<region>.digitaloceanspaces.com	Spaces のアクセスキーを使用します
Scaleway	https://s3.<region>.scw.cloud	Scaleway のアクセスキーを使用します
Ceph RGW	http://<rgw-host>:<port>	エンタープライズ向けのセルフホスト型で、すべての S3 API をサポートします
SeaweedFS	http://<master>:8333	S3 API を備えた高スループットの分散ファイルシステムです
Garage	http://<node>:3900	ホームラボ向けの軽量な分散 S3 です

# 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

プライベート CA を使った TLS： MinIO、RustFS、または Ceph で自己署名証明書を使用する場合は、--ca-file /path/to/ca.pem を追加してください。

Azure Blob Storage

DefaultAzureCredential を使用します。AZURE_TENANT_ID／AZURE_CLIENT_ID／AZURE_CLIENT_SECRET 環境変数、マネージド ID、az login などで利用できます。

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

Google Cloud Storage

Application Default Credentials（ADC）を使用します。GOOGLE_APPLICATION_CREDENTIALS を設定するか、gcloud auth application-default login を実行してください。

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

インメモリー（エフェメラル）

設定不要、依存関係なしのプロバイダーです。すべてのデータは Map に保存され、プロセスの終了時に失われます。

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

SQLite（ローカル永続ストレージ）

WAL モードを使用したローカル永続ストレージです。ランタイムを自動で切り替えます。Bun では bun:sqlite、Node.js では better-sqlite3 を使用します（ピア依存関係としてインストールしてください：npm install better-sqlite3）。

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

---

MCP クライアント設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %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：

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

リモート HTTP クライアント

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

---

ツールリファレンス

すべてのパスはクラウド URI です。例：s3://my-bucket/path/to/file.txt。サーバーは起動時に各パスを設定済みのルート URI と照合して検証し、許可されたルート外へのリクエストは拒否されます。

読み取りツール

ツール	パラメーター	説明
read_file	path	ファイルを読み込みます。バイナリは Base64、テキストは UTF-8 で返します。
read_text_file	path、head?、tail?	先頭／末尾の行数を任意で指定して、テキストファイルを読み込みます。
read_media_file	path	画像／メディアを Base64 の MCP 画像コンテンツブロックとして読み込みます。
read_multiple_files	paths	複数のファイルを並列に読み込みます。
read_file_range ✨	path、offset、limit	総行数をヘッダーに含めて、1 始まりの行範囲を読み込みます。
read_file_chunk ✨	path、start_byte、end_byte?、encoding?	ファイル全体をダウンロードせずに、バイト範囲を読み込みます。最大 10MB です。

書き込みツール

ツール	パラメーター	説明
write_file	path、content	ファイルを書き込み／上書きします。デバウンス時間の経過後にフラッシュされます。
edit_file	path、edits[]、dryRun?、expected_etag?	{ oldText, newText } の編集を適用します。dryRun でプレビューできます。ETag による競合検出も任意で行えます。

ディレクトリツール

ツール	パラメーター	説明
create_directory	path	ディレクトリのプレースホルダーと親ディレクトリのプレフィックスを作成します。
list_directory	path	直下の子要素を一覧表示します（ls と同様）。
list_directory_with_sizes	path、sortBy?、limit?	子要素をサイズとともに一覧表示します。サイズまたは名前で並べ替えます。
directory_tree	path、excludePatterns?	glob による除外に対応した、再帰的なディレクトリツリーです。

移動、コピー、削除ツール

ツール	パラメーター	説明
move_file	source、destination	ファイルを移動します。同一バケットの場合は、サーバー側でコピーしてから削除します。
copy_file ✨	source、destination	ファイルをコピーします。同一バケットの場合はサーバー側でコピーします。
delete_file ✨	path	ファイルを削除します。--enable-delete が必要です。

検索ツール

ツール	パラメーター	説明
search_files	path、pattern、excludePatterns?	glob ベースでオブジェクトキーを検索します。
grep_file ✨	path、pattern、case_insensitive?	1 つのファイルを行番号付きで正規表現検索します。
grep_files ✨	path、pattern、glob?、case_insensitive?、output_mode?、max_objects?	パス配下のすべてのオブジェクトを正規表現検索します。

情報ツール

ツール	パラメーター	説明
get_file_info	path	ファイルのメタデータ：サイズ、最終更新日時、コンテンツタイプ。
list_allowed_directories	(なし)	設定済みのルート URI を一覧表示します。

✨ = 拡張ツール

クラウドネイティブツール ☁️

ツール	パラメーター	説明
get_presigned_url ☁️	path、operation?、expires_in?	一時的なアクセス URL を生成します（デフォルト：GET、1 時間）。
get_object_metadata ☁️	path	サイズ、コンテンツタイプ、最終更新日時、カスタムメタデータ、タグ。
set_object_tags ☁️	path、tags	オブジェクトのタグをキーと値のペアで置き換えます。
search_by_tag ☁️	path、tags、recursive?	タグフィルター（AND ロジック）に一致するオブジェクトを検索します。
list_versions ☁️	path、max_results?、page_token?	タイムスタンプ、サイズ、マーカーを含むバージョン履歴です。
restore_version ☁️	path、version_id	オブジェクトの以前のバージョンを復元します（現在のオブジェクトを上書きしてコピーします）。

☁️ = クラウドネイティブツール（プロバイダーのサポートが必要です）

AI ネイティブツール 🧠

ツール	パラメーター	説明
get_file_schema 🧠	path	構造スキーマを抽出します：CSV の列名／型／サンプル、JSON の構造、またはテキストの行数／バイト数。
summarize_file 🧠	path、max_lines?	ファイルサイズ、行数、コンテンツタイプを含む、先頭／末尾の簡潔なプレビューです。

🧠 = AI ネイティブツール（LLM コンテキストトークンの無駄を削減します）

マクロツール 🩹

ツール	パラメーター	説明
patch_file 🩹	path、patch、format?、expected_etag?	1 回のツール呼び出しで、統一差分または行範囲置換をアトミックに適用します。

🩹 = マクロツール（読み取り＋変換＋書き込みを組み合わせます）

シェルツール ⚡

ツール	パラメーター	説明
shell ⚡	command	POSIX に類似したコマンドを実行します。パイプとリダイレクトに対応しています。--enable-shell が必要です。

組み込みコマンド： ls、cat、head、tail、cp、mv、rm、mkdir、touch、stat、find、grep、wc、du、echo、tee、diff、jq、cd

相対パス

すべてのシェルコマンド（およびその他すべてのツール）は相対パスに対応しているため、毎回 URI 全体を入力する必要はありません。スキームプレフィックス（s3://、mem:// など）のないパスは、最初に設定されたルートを基準に解決されます。

# 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'"

標準の . と .. は正規化され、セキュリティのため、ルート境界を越える .. による移動はブロックされます。

例

# 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"

⚡ --enable-shell が必要です。rm と mv には、さらに --enable-delete が必要です。

---

アーキテクチャ：仮想ファイルシステム（VFS）

すべてのツール操作は、FUSE に着想を得た 仮想ファイルシステム（VFS） レイヤーを介して実行されます。

┌─────────────────────────────────────────────────────────┐
│  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) │
└─────────────────────────────────────────────────────────┘

操作	解決方法
get()	キャッシュヒット → 返却します。削除済み → 例外をスローします。それ以外 → プロバイダーにフォールバックします。
stat()	inode オーバーレイ → キャッシュされたコンテンツサイズ → プロバイダーの headObject。
list()	プロバイダーの一覧 – 削除済み項目 + オーバーレイの dirIndex エントリー。
put()	キャッシュに設定 + markDirty + inode を更新 + dirIndex。即座に反映されます。
remove()	プロバイダーの deleteObject + キャッシュを削除 + 削除済みとして記録。即座に表示されなくなります。

VFS メタデータは、__vfs__/* キーを使って CacheStore に永続化されます。起動時に VirtualFS.hydrate() が状態を復元し、破損したデータは通知なしに破棄されます。

---

キャッシュ

バックエンド	フラグ	備考
メモリ（デフォルト）	--cache-store memory	プロセス内で動作し、高速ですが、共有も永続化もされません。
ファイルシステム	--cache-store fs --cache-dir <path>	再起動後も保持されます。
Redis	--cache-store redis	共有可能で、永続化されます。ピア依存関係として ioredis が必要です。REDIS_URL 環境変数を使用します。TLS には rediss:// を使用してください。

書き込みは即座にキャッシュに反映され（ダーティとしてマークされます）、デバウンス期間（デフォルト：2s）の経過後にフラッシュされます。正常なシャットダウンでは、終了前にすべてのダーティエントリーがフラッシュされます。パススルーモード（--no-cache）では、すべての操作がプロバイダーに直接送信されます。

⚠️ Redis TLS： REDIS_URL が暗号化されていない redis:// を使用している場合、サーバーは起動時に警告を表示します。本番環境では、TLS 暗号化接続に rediss:// を使用してください。

カスタム CA 証明書

プライベート CA を使用している S3 互換エンドポイント（MinIO、RustFS）や Redis に PEM CA バンドルを指定するには、--ca-file <path> を使用します。

# 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

実行環境全体の CA 信頼（すべてのプロバイダーと Redis）を設定するには、代わりに標準の NODE_EXTRA_CA_CERTS 環境変数を使用します。

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

---

プログラムからの使用（npm ライブラリ）

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 });

エクスポートされる API

エクスポート	説明
createMcpServer(ctx)	設定済みの MCP サーバーインスタンスを作成します
executeShell(command, ctx)	VFS に対して POSIX 風のコマンドを実行します
VirtualFS	FUSE に着想を得たライトバックオーバーレイ
MemoryStore, FilesystemStore, createRedisStore, PassThroughCache	キャッシュバックエンド
S3Provider, AzureProvider, GcsProvider, MemoryProvider, SqliteProvider, MultiProvider	ストレージプロバイダー
CloudError, CloudErrorCode	クラウド対応の構造化エラー処理
checkHealth, formatHealthReport	接続のヘルスチェックユーティリティ
AuditLogger, StderrAuditSink, FileAuditSink	ツール呼び出しの監査ログ
parseUri, toCacheKey, resolveToolPath	パスユーティリティ
ShellContext, ShellCommandHandler	シェル拡張用の型

---

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：インタラクティブシェル（xterm.js）

アプリをビルドします：bun run build:app → dist/app/shell-app.html を出力します。

Catppuccin Mocha テーマ、コマンド履歴、自動リサイズに対応しています。MCP Apps 拡張機能を介して、互換性のある MCP ホスト（Claude Desktop）内に表示されます。

---

開発とテスト

セットアップ手順の詳細は、CONTRIBUTING.md を参照してください。

AI エージェントのスキルは、クローン後に bun x skills add semgrep/skills で別途インストールします。詳細は CONTRIBUTING.md を参照してください。

テストの層

層	コマンド	インフラが必要か
ユニット	bun run test	いいえ
E2E（HTTP）	bun run test:e2e:http	いいえ
E2E（インフラ）	bun run test:e2e:infra	Docker
統合	bun run test:integration	Docker
すべて	bun run test:all	Docker

CI パイプライン

CI ワークフローは、プッシュまたは PR のたびに実行されます。

1. ci ジョブ：lint → typecheck → ユニットテスト（カバレッジ付き）→ HTTP E2E → ビルド
2. e2e ジョブ：Docker Compose（MinIO、Redis）を使用した完全な E2E

HTTP E2E テストはメモリ内プロバイダーを使用し、インフラを一切必要としないため、すべての CI 実行で高速かつ確実に実行できます。

---

AI エージェントスキル

skills/cloud-fs ディレクトリには、コーディングアシスタント（Claude Code、Gemini CLI など）に cloud-fs を POSIX に似た仮想ファイルシステムとして使う方法を教える、インストール可能な AI エージェントスキルが含まれています。インストールすると、アシスタントがクラウドストレージのコマンドを使いこなせるようになります。

提供する機能

• MCP モードの自動検出 — mcp__cloud-fs__* ツールを認識し、ユーザーの意図に適したツール呼び出しに対応付けます
• 初期設定フロー — MCP サーバーがまだ設定されていない場合、初回セットアップをユーザーに案内します
• POSIX から MCP へのマッピング — シェルコマンド（ls、cat、grep、find、cp など）を適切な MCP ツール呼び出しに変換します
• プロバイダーの認証情報リファレンス — AWS、Azure、GCS、MinIO/RustFS、SQLite のセットアップ方法を案内します
• .mcp.json への保存 — プロバイダー設定の保存を提案し、次回以降のセッションで事前に設定された状態にします

インストール

# 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

スキルシステムの詳細については、CONTRIBUTING.md を参照してください。

---

ドキュメント

完全なドキュメントは nogoo9.github.io/mcp-server-cloud-fs でご覧いただけます。

• 📖 各リリースのバージョン別ドキュメント（v0.4.0 以降）
• 🔄 オープンなプルリクエストのプレビュー用ドキュメント
• 🔍 全文検索、ダークモード、レスポンシブデザイン
• VitePress で構築

ドキュメントサイトをローカルで実行するには、次のコマンドを使います。

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

---

ライセンス

PolyForm Shield 1.0.0。競合しない用途であれば、無料でご利用いただけます。

---

を使用して構築