FileSystem MCP Server

FileSystem MCP Server

バージョン：0.1.4 — 最終更新日：2026-10-13

Visual Studio 2022+ 向けのローカル MCP サーバーです。AI エージェントにプロジェクトのフォルダーとファイルへの選択的なアクセスを提供し、コードワークスペース機能を実現します。

目次

• 🎯 対象環境
• 機能
• インストール
• クイックスタート
• 設定オプション
  • オプション 1：Config.json ファイル（最も簡単 — 初心者におすすめ）
  • オプション 2：コマンドライン引数（上級者向け — MCP クライアント用）
  • オプション 3：ハイブリッド方式（両方の利点を活用）
• 使い方
  • コマンドラインの例
  • 利用可能なツール
• このハイブリッド方式が最適な理由
• Visual Studio 2022+ でのデバッグ
• Visual Studio 2022+ の使用例
• GitHub Copilot Chat での mcp.json ファイルの編集
• セキュリティ
• エラー処理
• トラブルシューティング
  • MCP 設定に関する問題
  • Visual Studio 2022+ でのデバッグ
  • よくある問題
• コマンドラインリファレンス
• クロスプラットフォームのパスサポート
• 高度な実用的 MCP 設定例

---

🎯 対象環境

この MCP サーバーは、次の用途に最適化されています。

• Visual Studio 2022+ での開発ワークフロー
• 複雑なワークスペース設定を必要としないローカル開発環境
• ファイルシステム操作が必要なフォルダーへの直接アクセス
• .code-workspace ファイルを使用しない開発環境
• マルチルートワークスペースではなく、個々のプロジェクトディレクトリ

機能

• ディレクトリの走査：許可されたディレクトリの内容を一覧表示します
• ファイルの読み取り：許可された拡張子のファイルの内容を読み取ります
• ファイルの書き込み：ファイルにテキスト／バイナリコンテンツを書き込みます — --allow-write で明示的に有効化（デフォルトでは無効）
• ディレクトリの検証：設定したディレクトリにアクセスできるか確認します
• ハイブリッド設定：コマンドライン引数（MCP）＋ config.json によるフォールバック（デバッグ）
• Visual Studio 2022+ でのデバッグ：引数なしでの起動に対応
• クロスプラットフォームのパスサポート：Windows（\）と Unix（/）の両方のパス区切り文字を自動的に処理します
• セキュリティ：アクセスは、明示的に指定されたディレクトリとファイル形式に制限されます
• ローカル開発に最適：Visual Studio 2022+ や同様の環境に最適です

インストール

PyPI から（ユーザーにおすすめ）

pip install vs-filesystem-mcp-server

ソースから（開発者向け）

1. Python 3.10+ がインストールされていることを確認します

2. リポジトリをクローンします

3. プロジェクトディレクトリに移動します

4. uv を使って依存関係をインストールします。

   uv sync
   

クイックスタート

1. MCP で使用する場合：修正済みの設定を .mcp.json に追加します
2. デバッグする場合：Visual Studio 2022+ で F5 を押すだけです。config.json が自動的に使用されます
3. 最初に init() ツールを呼び出して、設定をテストします
4. init() がエラーを返す場合は、ディレクトリのパスとアクセス権を確認します

設定オプション

オプション 1：Config.json ファイル（最も簡単 — 初心者におすすめ）

最も簡単な始め方です！ config.json ファイルを作成します。

MCP サーバーとして使用する場合：

• .mcp.json ファイルと同じフォルダー（通常は C:\Users\YourUsername\）に config.json を配置します

ソースからデバッグする場合（Visual Studio 2022+）：

• app.py と同じディレクトリ（D:/Projects/filesystem_server/）に config.json を配置します

{
  "allowed_dirs": [
    "C:/Users/YourUsername/Documents/projects",
    "D:/projects",
    "D:/Webs"
  ],
  "allowed_extensions": [
    ".py", ".js", ".ts", ".json", ".md", ".txt",
    ".yml", ".yaml", ".toml", ".cfg", ".ini", ".cs",
    ".css", ".scss", ".htm", ".html", ".xml", ".xaml"
  ],
  "allow_write": false
}

注： write_file ツールと write_file_binary ツールを有効にするには、"allow_write": true を設定します。

MCP の設定（pip でインストールした場合）

.mcp.json ファイルに以下を追加します（通常、VS 2022 以降では C:\Users\YourUsername\ にあります）。

{
  "servers": {
    "filesystem-server": {
      "command": "vs-filesystem-mcp-server"
    }
  }
}

注： pip でインストールした場合、コマンドは vs-filesystem-mcp-server だけです。app.py へのパスは必要ありません！

MCP の設定（ソースから実行する場合）

開発中で、ソースコードから実行する場合：

{
  "servers": {
    "filesystem-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/project/filesystem_server/app.py"
      ],
      "cwd": "/absolute/path/to/your/project/filesystem_server"
    }
  }
}

メリット：

• ✅ コマンドライン引数が不要
• ✅ Visual Studio 2022 でのデバッグに最適（F5 キーを押すだけです）
• ✅ 正しい場所に配置すれば MCP クライアントで動作
• ✅ 簡単に編集・変更可能
• ✅ テストや開発に最適

使い方：

# For debugging in Visual Studio 2022:
python app.py  # Uses config.json from same directory as app.py

# For MCP server usage:
# The MCP client automatically finds config.json in the .mcp.json directory

配置場所に関する重要な注意事項：

• 🔧 デバッグ：config.json は app.py の隣に配置します
• 🌐 MCP サーバー：config.json は .mcp.json の隣に配置します
• 📁 用途によって配置場所が異なります！

オプション 2：コマンドライン引数（上級者向け — MCP クライアント用）

すべての設定を一か所にまとめたい、本番環境の MCP クライアント設定に最適です。

pip でインストールした場合

{
  "servers": {
    "filesystem-server": {
      "command": "vs-filesystem-mcp-server",
      "args": [
        "--allowed-dirs", "D:/projects", "D:/Webs",
        "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt"
      ]
    }
  }
}

ソースから実行する場合

python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

# With write access enabled:
python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md" --allow-write true

MCP クライアントの設定（.mcp.json）：

{
  "servers": {
    "filesystem-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/project/filesystem_server/app.py",
        "--allowed-dirs", "D:/projects", "D:/Webs",
        "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt"
      ],
      "cwd": "/absolute/path/to/your/project/filesystem_server"
    }
  }
}

メリット：

• ✅ 設定が自己完結
• ✅ 外部設定ファイルが不要
• ✅ バージョン管理に適しています
• ✅ MCP の設定内で明示され、確認しやすい

オプション 3：ハイブリッド方式（両方の利点を活用）

サーバーはまずコマンドライン引数を使用し、引数が指定されていない場合は自動的に config.json にフォールバックします。

仕組み：

• MCP クライアント：コマンドライン引数を使用します（オプション 2）
• Visual Studio でのデバッグ：config.json を自動的に使用します（オプション 1）
• 優先順位：コマンドライン引数が指定されている場合、config.json より優先されます

メリット：

• ✅ MCP クライアントとデバッグの両方で動作
• ✅ 用途ごとの設定が競合しません
• ✅ 柔軟で開発者にとって使いやすい
• ✅ 状況に応じて最適な方法を選択できます

使い方

コマンドラインの例

# With command line arguments (MCP clients):
python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

# Using config.json fallback (Visual Studio 2022+ debugging):
python app.py

# Show MCP configuration help:
python app.py --help-mcp

利用可能なツール

1. init(directory, file_path) - 設定済みディレクトリへのアクセスを検証し、オプションでディレクトリの一覧表示やファイルの読み取りを行います

   • directory（オプション）：内容を一覧表示するディレクトリのパス（None を指定できます）
   • file_path（オプション）：内容を読み取るファイルのパス（None を指定できます）
   • すべてのディレクトリにアクセスできる場合、{ "message": "OK", "isError": false, ... } を返します
   • アクセスできないディレクトリがある場合、エラーの詳細を返します
   • 設定元（コマンドライン引数または設定ファイル）を表示します
   • 他のツールを使用する前に、設定の確認に使用します

2. list_directory(directory, report_progress=True, batch_size=100) - 指定したディレクトリ内のファイルとサブディレクトリを一覧表示し、オプションで進捗を報告します

   • directory：ディレクトリへの絶対パスまたは相対パス（/ と \\ の両方の区切り文字に対応）
   • report_progress（オプション）：True の場合、進捗情報とバッチの詳細を返します（デフォルト：True）
   • batch_size（オプション）：進捗を報告するまでに処理する項目数（デフォルト：100）
   • report_progress が False の場合、ファイル名とディレクトリ名のリストを返します
   • report_progress が True の場合、内容、progress_info、total_items、processing_time を含む辞書を返します
   • エラーが発生した場合、"error" と "error_message" のキーを含む辞書を返します
   • 例外は発生しません。すべてのエラーは結果の一部として返されます

3. read_file(file_path) - 指定したファイルの内容をテキストとして読み取ります

   • ファイルの内容を文字列として返します（テキストファイルのみ）
   • バイナリファイル（画像、音声など）には適していません

4. read_file_binary(file_path) - 指定したファイルの内容を Base64 エンコードされたバイナリとして読み取ります

   • 成功時は { "content_base64": <base64 string>, "encoding": "base64", "error": False } を返します
   • ファイルが許可されていない場合、または見つからない場合はエラー辞書を返します
   • 画像、音声、その他のバイナリファイルに適しています

5. list_resources(directory=None, report_progress=True, batch_size=100) - ディレクトリ（または許可されているすべてのディレクトリ）にあるすべてのリソース（ファイルとディレクトリ）を MCP リソース形式で一覧表示します

   • directory（省略可）：開始するディレクトリ（デフォルトはすべての allowed_dirs）
   • report_progress（省略可）：True の場合、進捗情報とバッチを返します（デフォルト：True）
   • batch_size（省略可）：進捗バッチあたりのリソース数（デフォルト：100）
   • report_progress が False の場合、リソースオブジェクトのリストを返します
   • report_progress が True の場合、contents、progress_info、total_items、processing_time を含む辞書を返します
   • リソースオブジェクトの例：

     {
       "id": "D:/projects/example.txt",
       "type": "file",
       "name": "example.txt",
       "path": "D:/projects/example.txt",
       "metadata": {
         "size": 1234,
         "modified": "2025-08-18T12:34:56Z"
       },
       "actions": ["read", "read_binary", "write", "write_binary"]
     }
     

6. get_resource(path) - 指定したファイルまたはディレクトリのメタデータとアクションを取得します

   • path：リソースへの絶対パスまたは相対パス
   • リソースオブジェクト（id、type、name、path、metadata、actions）またはエラー辞書を返します
   • ファイルの場合はサイズと更新日時が含まれ、ディレクトリの場合はタイプとアクションが含まれます
   • ファイルの内容は返しません

7. write_file(file_path, content) - 指定したファイルにテキストコンテンツを書き込みます（--allow-write が必要です）

   • file_path：書き込み先のパス（許可されたディレクトリ内である必要があります）
   • content：書き込むテキスト文字列
   • 書き込みアクセスが無効、パスが許可されていない、拡張子が許可されていない、または I/O エラーが発生した場合は ValueError を発生させます
   • 既存のファイルを上書きします
   • デフォルトでは無効です — --allow-write フラグ、または config.json の "allow_write": true で有効にします

8. write_file_binary(file_path, content_base64) - base64 からバイナリコンテンツをファイルに書き込みます（--allow-write が必要です）

   • file_path：書き込み先のパス（許可されたディレクトリ内である必要があります）
   • content_base64：base64 でエンコードされたバイナリデータ
   • {"success": true, "bytes_written": int, "error": false} またはエラー辞書を返します
   • 既存のファイルを上書きします。画像やバイナリに適しています
   • デフォルトでは無効です — --allow-write フラグ、または config.json の "allow_write": true で有効にします

このハイブリッド方式が最適な理由

• ✅ MCP クライアント：効率的なコマンドライン引数を使用できます
• ✅ Visual Studio 2022：config.json によるフォールバックで、手間なくデバッグできます
• ✅ 競合なし：優先順位システムが両方のシナリオを適切に処理します
• ✅ 開発者に優しい：希望する方法で実行できます
• ✅ 両方の利点：MCP の効率性とデバッグの利便性を兼ね備えています

Visual Studio 2022+ でのデバッグ

最適なデバッグ体験：

• ✅ コマンドライン引数は不要です
• ✅ F5 を押すだけでデバッグを開始できます
• ✅ config.json が自動的に使用されます
• ✅ ブレークポイントを設定して通常どおりデバッグできます
• ✅ IntelliSense とデバッグ機能をすべて利用できます

デバッグのセットアップ：

1. Visual Studio 2022 でプロジェクトを開きます
2. config.json が存在することを確認します（すでに作成済みです）
3. F5 を押すか、［デバッグ］>［デバッグの開始］を選択します
4. 設定したディレクトリでサーバーが起動します

Visual Studio 2022+ の使用例

以下では、Visual Studio 2022 内から FileSystem MCP Server を呼び出す手順を、段階を追って説明します。これらのスクリーンショットでは、サーバーのエイリアスとして 「fss」 を使用しています。これは "filesystem-server" の短縮名にすぎません。このエイリアスは .mcp.json ファイルでカスタマイズできます。実際に使用する名前は自由です。

注： 画像はすべて images/ サブフォルダーにあります。

ステップ 1：サーバーツールの呼び出し

この例では、MCP クライアントがサーバー名として "fss" を使用するように設定されています。これは、使いやすさのためのエイリアスです。

ステップ 2：サーバーの応答を確認する

サーバーは、read_file() ツールの出力など、リクエストの結果を返します。

---

注：

• ここでは簡潔にするため、エイリアスとして "fss" を使用しています。.mcp.json の設定では、任意の名前を使用できます。
• サーバー名を変更するには、.mcp.json ファイルのキーを "filesystem-server" から任意の名前に変更してください。

MCP クライアントの設定について詳しくは、上記の設定オプションセクションをご覧ください。

GitHub Copilot Chat で mcp.json ファイルを編集する

GitHub Copilot Chat インターフェースを使えば、Visual Studio から mcp.json 設定ファイルを直接簡単に編集できます。次の手順に従ってください。

1. エージェントモードで、Visual Studio の右側にあるツールアイコンをクリックします。
2. リスト内の任意の MCP サーバーの横にある矢印をクリックします。
3. ［編集］を選択すると、mcp.json ファイルが編集用に開きます。

これにより、IDE を離れることなく、MCP サーバーの設定をすばやく更新できます。

セキュリティ

• --allowed-dirs または config.json で指定されたディレクトリにのみアクセスできます
• --allowed-extensions または config.json で指定された拡張子のファイルのみ読み取りまたは書き込みができます
• 書き込みアクセスはデフォルトで無効です：write_file と write_file_binary を使用するには、--allow-write フラグまたは config.json 内の "allow_write": true が必要です
• すべてのパスはアクセス前に検証されます
• サーバーはユーザーアカウントの権限で実行されます
• ローカル開発に最適です：プロジェクトディレクトリに安全にアクセスできます

エラー処理

サーバーは、次のエラーについて詳細なメッセージを提供します。

• 許可されていないディレクトリへのアクセス
• 無効なファイルパス
• サポートされていないファイル拡張子
• 設定の不足（MCP とデバッグの両方の状況に役立つガイダンスを表示します）
• ディレクトリへのアクセスに関する問題（init() ツール経由）

list_directory() の新しいエラー処理：

• list_directory() 関数は、例外を発生させる代わりに、結果リストの一部としてエラーを返すようになりました
• エラー形式：["error", "detailed_error_message"]
• これにより、MCP クライアントは例外処理を行わずにエラーを適切に処理しやすくなります
• 成功した呼び出しでは、通常のディレクトリ内容のリストが返されます

トラブルシューティング

MCP の設定に関する問題

元の設定では、"D:/Webs" の後にカンマが不足していました。上記の修正版では、この問題が解消されています。

Visual Studio 2022 以降でのデバッグ

1. config.json があることを確認します（対象のディレクトリ用にすでに作成されています）
2. init() ツールから開始して設定を検証します
3. ブレークポイントを設定して通常どおりデバッグします
4. 出力ウィンドウを確認して設定ソースが確認できることを確かめます

よくある問題

1. 設定の不足：サーバーは、MCP とデバッグの両方の状況に役立つメッセージを表示します
2. パスへのアクセスエラー：ディレクトリが存在し、アクセス可能であることを確認します
3. 権限の問題：設定したパスのディレクトリ権限を確認します
4. MCP クライアントの問題：上記の修正版設定を使用します

コマンドラインリファレンス

python app.py --help                         # Show help
python app.py --help-mcp                     # Show MCP configuration examples  
python app.py --allowed-dirs DIR1 DIR2       # Set allowed directories
python app.py --allowed-extensions EXT1 EXT2 # Set allowed extensions
python app.py --allow-write true             # Enable write tools (disabled by default)
python app.py --allow-write false            # Explicitly disable write tools
python app.py --config custom.json           # Use custom config file
python app.py                                # Use config.json fallback (debugging)

クロスプラットフォームのパスサポート

ファイルシステムサーバーは、異なるオペレーティングシステムの規則に対応するため、パスを自動的に正規化します。

✅ Windows ユーザー — どちらの形式も使用できます

{
  "allowed_dirs": [
    "D:\\projects",           // Windows-style backslashes
    "F:/sd/wipes",           // Unix-style forward slashes  
    "C:\\Users\\Me\\Docs"    // Mixed formats work too
  ]
}

✅ パスの自動正規化

• 入力："F:\sd\wipes"（Windows の一般的な形式）
• 正規化後："F:/sd/wipes"（Python で扱いやすい形式）
• 結果：✅ 問題なく動作し、エラーは発生しません！

✅ MCP ツールの例

# All of these work identically:
list_directory("F:\\sd\\wipes")    # Windows format
list_directory("F:/sd/wipes")      # Unix format  
list_directory("F:\\sd/wipes")     # Mixed format

これが重要な理由

• 🪟 Windows ユーザーは、自然に F:\sd\wipes と入力できます
• 🐧 Unix ユーザーは、従来の F:/sd/wipes を使用できます
• 🔧 パス形式のエラーがなくなります — すべて問題なく動作します
• 🛡️ セキュリティチェックは、区切り文字の形式に関係なく正しく動作します

高度な MCP 設定例と実用的な MCP 設定例

"servers" 形式と "mcpServers" 形式の両方を含む、より高度なプラットフォーム固有の設定例やレガシー MCP クライアントの設定例については、このリポジトリの mcp_configuration_examples.json ファイルをご覧ください。

このファイルには、以下の内容が含まれています。

• Windows、Linux、macOS 向けの実用的な設定例
• 最小限のウェブ開発用設定
• 複数のディレクトリとファイルタイプの例
• config.json からコマンドライン引数への移行に関するヒント
• "mcpServers" 形式を使用するレガシー MCP クライアントのサポート

より柔軟な設定が必要な場合や、標準的でない MCP クライアントを使用している場合は、こちらを参照してください。