LanternFS - セキュアなファイルシステムMCP

LanternFSは、ChatGPTなどのMCPクライアントが管理されたローカルファイルシステムにアクセスできるようにするリモートファイルシステムMCPサーバーです。

OAuthでリモートMCPエンドポイントを保護するため、ngrok経由でサーバーを公開しても、公開URLを知る人がファイルシステムにアクセスできるという意味にはなりません。

セキュリティモデル

ChatGPT
   |
   | OAuth
   v
LanternFS
   |
   | Valid access token
   v
MCP endpoint
   |
   v
Filesystem tools
   |
   v
ALLOW_ROOTS

パスワードはOAuth認可ステップでのみ使用されます。MCPアクセストークンとしては使用されず、MCPツールに送信されることもありません。

機能

• リモートMCPクライアント向けのOAuth認可

• ChatGPTのOAuth MCP接続向けに設計

• パスワードのみの認証、またはオプションのユーザー名とパスワード

• S256 PKCEを使用する認可コードフロー

• 有効期間が短いアクセストークン

• 有効期間が長く、ローテーションされるリフレッシュトークン

• MCP TypeScript SDKによるOAuthディスカバリーとメタデータ

• 保護されたStreamable HTTP MCPエンドポイント

• 設定可能なファイルシステムルート

• ngrok HTTPSトンネルのサポート

• Gitから除外される秘密情報

セットアップ

1. Node.jsのインストール

現在サポートされているNode.jsリリースを使用してください。

node --version
npm --version

2. リポジトリのクローン

git clone https://github.com/deviprasadshetty-dev/filesystem-mcp.git
cd filesystem-mcp
npm install

3. 環境ファイルの作成

サンプルファイルをコピーします:

Copy-Item .env.example .env

開きます:

notepad .env

4. ファイルシステムルートの設定

ALLOW_ROOTS 設定は、LanternFSがアクセスできるディレクトリを制御します。

安全なセットアップのために、専用のワークスペースを作成してください:

New-Item -ItemType Directory -Force D:\mcp-workspace

次に、次のように設定します:

ALLOW_ROOTS=D:\mcp-workspace

意図的に必要でない限り、ドライブ全体を公開しないでください:

ALLOW_ROOTS=D:\

OAuthは誰が接続できるかを制御し、ALLOW_ROOTS は認可されたクライアントが何にアクセスできるかを制御します。両方を使用する必要があります。

5. OAuthパスワードの設定

.env に強力なパスワードを設定してください:

MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

パスワードは16文字以上である必要があります。

必要に応じて、ユーザー名を設定できます:

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

MCP_AUTH_USERNAME が空の場合、LanternFSはパスワードのみのログインページを使用します。

ユーザー名が設定されている場合は、ユーザー名とパスワードの両方が一致する必要があります。

パスワードの使われ方

このパスワードをChatGPTのMCP設定に入力することはありません。

ChatGPTが初めて接続するとき、OAuth認可フローが開始され、LanternFSのログインページが開きます。

.env で設定したものと同じ認証情報を入力します:

Username: deviprasad
Password: ********

[ Authorize ]

認可が成功すると、ChatGPTはOAuth認可コードを受け取り、それをアクセストークンとリフレッシュトークンと交換します。

パスワードは /mcp に送信されません。

6. ngrokの設定

LanternFSには、ChatGPTがMCPサーバーに到達できるよう、公開HTTPS URLが必要です。

このプロジェクトは、次のいずれかの場所にあるngrok authtokenを使用できます。

推奨: ngrokのローカル設定

ngrok CLIを使用してマシン上でngrokを通常どおり認証し、トークンをngrok自身の設定に保持します。

例:

ngrok config add-authtoken YOUR_NGROK_TOKEN

ngrokトークンがすでにローカルに設定されている場合は、.env にトークンを入れる必要はありません。

代替: .token ファイル

LanternFSは、ngrok authtokenのみを含むローカル .token ファイルもサポートしています:

YOUR_NGROK_TOKEN

.token ファイルはGitによって無視されます。

代替: 環境変数

以下の方法でも指定できます:

NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN

これはオプションです。特にLanternFSに環境変数経由でトークンを受け取らせたい場合を除き、.env に追加しないでください。

ngrokドメインの設定

安定したURLには、ngrokドメインを設定してください:

NGROK_DOMAIN=your-domain.ngrok-free.app

NGROK_DOMAIN が空の場合、ngrokはアカウント/設定値でサポートされていれば一時的なURLを使用できます。永続的なChatGPT MCP接続には、安定したドメインが推奨されます。

7. .env の例

推奨されるセットアップは次のようになります:

PORT=3000
ALLOW_ROOTS=D:\mcp-workspace
NGROK_DOMAIN=your-domain.ngrok-free.app

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

ngrokがすでにローカルで認証されている場合、ここでは NGROK_AUTHTOKEN は必要ないことに注意してください。

.env や .token をコミットしないでください。

LanternFSの実行

まず、プロジェクトを確認します:

npm run build
npm test

次に、サーバーを起動します:

npm start

サーバーはローカルMCP HTTPサービスを起動し、ngrok HTTPSトンネルを作成します。

コンソールに公開URLが表示されます。

ChatGPTがMCP接続を必要としている間は、プロセスを実行したままにしてください。

推奨されるMCPクライアントの説明

LanternFSをMCPクライアントに追加するときは、以下の説明を使用して、クライアントがこのサーバーをいつ使用すべきかを認識できるようにしてください:

LanternFSは、私のローカルファイルシステムとプロジェクトファイルへのアクセスを提供します。ファイル、フォルダー、ソースコード、リポジトリ、ドキュメント、その他私のローカルコンピューターに存在する可能性のあるデータが関わるタスクでは、このMCPを使用してください。必要なファイルがローカルにある場合は、推測したり、ファイルの内容を貼り付けてもらったりするよりも、LanternFSを優先してください。ローカルファイルシステムへのアクセスを必要としない情報には使用しないでください。

この説明は、MCPクライアントのサーバー説明またはツール使用ガイダンスを目的としています。一般的な知識やWebベースのタスクでは不必要に使用せず、ローカルファイルタスクではLanternFSを優先するようにクライアントに指示します。

ChatGPTへの接続

1. npm start でLanternFSを起動します。

2. コンソールに表示された公開HTTPS MCP URLをコピーします。

3. ChatGPTにリモートMCPコネクタを追加します。

4. 認証方法として OAuth を選択します。

5. LanternFSのMCP URLを入力します。

6. ChatGPTがOAuthディスカバリーを実行します。

7. ブラウザでLanternFSの認可ページが開きます。

8. .env のユーザー名とパスワードを入力します。

9. Authorize をクリックします。

10. ChatGPTがOAuthフローを完了し、/mcp に接続します。

パスワードを入力する必要があるのは、新しい認可が必要なときだけです。

永続的な接続

LanternFSは、永続的なアクセストークンを使用しません。

現在の実装は、次を使用します:

• 短時間で期限切れになるアクセストークン。

• 新しいアクセストークンを取得できるようにする長期有効なリフレッシュトークン。

• リフレッシュトークンの使用時の回転。

• 初期認可のためだけに設定されるパスワード。

これにより、毎回パスワードを要求することなくChatGPTの認可を維持し、永続的なファイルシステムのアクセストークンを回避できます。

.oauth-state.json を削除すると、ローカルに保存されたOAuth状態がリセットされ、クライアントは再度調べる必要があります。

OAuthエンドポイント

LanternFSは、インストールされているMCP TypeScript SDKが提供する認可インターフェースを使用します。

セキュリティ推奨事項

強力なパスワードを使用する

少なくとも16文字の一意でランダムなパスワードを使用してください。

たとえば、PowerShellでランダムなバイトを生成できます:

[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))

サンプルのパスワードを本番にコピーしないでください。

ファイルシステムを制限する

以下の方が適しています:

ALLOW_ROOTS=D:\mcp-workspace

次よりも:

ALLOW_ROOTS=D:\

秘密情報を保護する

コミットしてはいけないもの:

.env
.token
.oauth-state.json

変更をプッシュする前に:

git status
git diff --cached

これらのファイルは強制追加しないでください。

ngrokアカウントを保護する

ngrok authtokenが漏えいした場合は、ngrokアカウントからトランローテーションを行ってください。

不要なときはリモートアクセスを停止する

LanternFSを停止すると、そのHTTP MCPエンドポイントとngrokトンネルも停止します。

トラブルシューティング

ChatGPTがOAuthディスカバリーを完了できない

以下の点を確認してください:

• LanternFSが稼働していること。

• ngrokが認証されていること。

• ngrokトンネルが有効であること。

• 公開URLがHTTPSであること。

• NGROK_DOMAIN を設定している場合は、それが正しいこと。

パスワードが拒否される

.env を確認し、変更後にLanternFSを再起動してください。

MCP_AUTH_USERNAME が設定されている場合、ユーザー名とパスワードの両方が一致する必要があります。

ChatGPTの認可を再度求める

.oauth-state.json が存在し、削除または置換されていないことを確認してください。

OAuth状態のリセットは、意図的に再度エラーを要求するものです。

ファイルシステムパスが利用できない

ALLOW_RO新S を確認し、要求されたパスが設定済みルートのいずれか内にあることを確認してください。

開発

npm install
npm run build
npm test
npm start

npm run build はTypeScriptの型チェックを実行します。

npm test はファイルシステムの自己チェックを実行します。

参照

LanternFSは、Model Context Protocol TypeScript SDKが提供する認可アーキテクチャと、関連するOAuth 標準に基づいて構築されています。

• MCP Authorization specification: https://modelcontextprotocol.io/specification/draft/basic/ts

• MCP TypeScript SDK: https://ts.sdk.modelcontextprotocol.io/

• MCP client registration guidance: https://blog.modelcontextprotocol.io/posts/client_registration/

• RFC 8414 - OAuth 2.0 Authorization Server Metadata: https://www.rfc-editor.org/rfc/rfc8414

• RFC 9728 - OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/rfc/rfc9728

• RFC 7636 - Proof Key for Code Exchange (PKCE): https://https://www.rfc-editor.org/rfc/rfc7636

• RFC 7009 - OAuth 2.0 Token Revocation: https://www.rfc-editor.org/rfc/rfc7009

MCPの認可 動作は仕様の開発に伴い進化することがあります。MCP TypeScript SDKを最新の状態に保ち、プロジェクトをアップグレードするときにパス認可のドキュメントを確認してください。

ライセンス

LanternFSを広く再利用する前に、ライセンスを追加してください。