Filesystem MCP Server for WSL

⚠️ 重要なお知らせ：
元の Filesystem MCP Server は、設定のパラメーターとしてネットワークパス \\wsl.localhost\DistributionName を指定するだけで、すでに WSL ファイルにアクセスできます。
例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "\\\\wsl.localhost\\Debian",
        "C:\\path\\to\\other\\allowed\\dir"
      ]
    }
  }
}

ただし、このプロジェクトでは、WSL の Linux ディストリビューションに特化して最適化された代替実装を提供しています。

公式サーバーが Node.js の fs モジュールを使ってディレクトリを再帰的に走査するのに対し、この実装では WSL 内のネイティブ Linux コマンド（find、grep など）を活用するため、ファイル一覧の取得やコンテンツ検索の処理が大幅に高速化します。

これは、大規模なディレクトリツリーを扱う場合や、検索パフォーマンスが重要な場合に特に役立ちます。

そのため、多くのユースケースではネイティブのネットワークパスを使うほうがシンプルですが、パフォーマンスの向上や、インデックス作成および検索ロジックをより柔軟に制御したい WSL ユーザーにとって、このプロジェクトは引き続き有用なソリューションです。

---

WSL 向け Filesystem MCP Server

Windows Subsystem for Linux（WSL）でのファイルシステム操作に特化した、Model Context Protocol（MCP）を実装する Node.js サーバーです。
このプロジェクトは、元の Filesystem MCP Server をフォークし、WSL 環境向けに全面的に再設計したものです。
汎用的なファイル操作を扱う元のプロジェクトとは異なり、このバージョンは WSL 上の Windows と Linux ディストリビューション間のシームレスな連携に特化しています。
両方のプロジェクトは互換性があり、同じシステム上で並行して実行できます。

機能

• Windows から任意の WSL ディストリビューションにアクセス
• Windows ホストから WSL 内のファイルを読み書き
• WSL 内のディレクトリを作成／一覧表示／削除
• WSL ファイルシステム内でファイル／ディレクトリを移動
• WSL 内のファイルを検索
• WSL ファイルシステムからファイルのメタデータを取得
• 複数の WSL ディストリビューションに対応

注：サーバーが許可する操作は、args で指定したディレクトリ内に限られます。

---

API

リソース

• wsl -d <distrib>：WSL ディストリビューションに対する操作に使うコマンド

ツール

• read_file

  • WSL からファイルの内容全体を読み込みます
  • 入力：path（文字列）
  • UTF-8 テキストとして内容を読み込みます

• read_file_by_parts

  • 大きなファイルを約 95,000 文字ずつに分割して読み込みます
  • 入力：
    • path（文字列）
    • part_number（正の整数：1、2、3 など）
  • 特長：
    • パート 1 はファイルの先頭から始まります
    • 後続のパートは行境界に揃えられます（調整は最大 300 文字）
    • 指定したパートが存在しない場合、実際のファイルサイズを含むエラーを返します
    • 1 回の操作で読み込むには大きすぎるファイルに便利です

• read_multiple_files

  • WSL から複数のファイルを同時に読み込みます
  • 入力：paths（文字列の配列）
  • 読み込みに失敗しても、操作全体は停止しません

• write_file

  • WSL でファイルを作成または上書きします（慎重に使用してください）
  • 入力：
    • path（文字列）
    • content（文字列）

• edit_file

  • 高度なパターンマッチングと書式設定による選択的な編集
  • 入力：
    • path（文字列）
    • edits（{ oldText, newText } の配列）
    • dryRun（ブール値、任意）
  • 特長：
    • 複数行のマッチング
    • インデントの保持
    • Git スタイルの差分プレビュー
    • 非破壊的なドライランモード

• create_directory

  • WSL でディレクトリを作成するか、存在を確認します
  • 入力：path（文字列）

• list_directory

  • [FILE] または [DIR] の接頭辞を付けてディレクトリの内容を一覧表示します
  • 入力：path（文字列）

• directory_tree

  • 内容を再帰的な JSON ツリー形式で表示します
  • 入力：path（文字列）

• move_file

  • ファイルまたはディレクトリを移動または名前変更します
  • 入力：
    • source（文字列）
    • destination（文字列）

• search_files

  • 名前で再帰的に検索します
  • 入力：
    • path（文字列）
    • pattern（文字列）
    • excludePatterns（文字列の配列、任意）

• search_in_files

  • ファイル内のテキストパターンを再帰的に検索します
  • 入力：
    • path（文字列）- 検索するルートディレクトリ
    • pattern（文字列）- 検索するテキストまたは正規表現パターン
    • caseInsensitive（ブール値、任意）- 大文字と小文字を区別しない検索
    • isRegex（ブール値、任意）- パターンを正規表現として扱います
    • includePatterns（文字列の配列、任意）- 対象に含めるファイルパターン（例：*.js）
    • excludePatterns（文字列の配列、任意）- 除外するファイルパターン
    • maxResults（数値、任意、既定値：1000）- 返す結果の最大数
    • contextLines（数値、任意、既定値：0）- 前後に表示するコンテキスト行数
  • 特長：
    • すべての特殊文字（アポストロフィ、引用符、$、バックスラッシュ）を処理します
    • プレーンテキスト検索と正規表現検索に対応します
    • マッチした行をファイルパスと行番号とともに表示します
    • .git、node_modules、.svn、.hg ディレクトリを自動的に除外します
    • マッチ箇所の前後のコンテキスト行を表示できます

• get_file_info

  • 詳細なメタデータを取得します
  • 入力：path（文字列）
  • 返却値：サイズ、タイムスタンプ、種類、アクセス許可

• list_allowed_directories

  • サーバーからアクセス可能なすべてのディレクトリを一覧表示します

• list_wsl_distributions

  • 利用可能なディストリビューションを一覧表示し、アクティブなものを示します

---

要件

• 適切に構成された Windows Subsystem for Linux (WSL)
• WSL に少なくとも 1 つの Linux ディストリビューションがインストールされていること

Claude Desktop ユーザー向け：
追加のインストールは不要です。claude_desktop_config.json を設定するだけです。

NPM パッケージ：
このパッケージは npm で入手できます：mcp-server-wsl-filesystem

開発向け：

• Node.js（v18.0.0 以上）
• TypeScript（開発依存関係として含まれています）

Windows への Node.js のインストール

1. nodejs.org からインストーラーをダウンロードします
2. 実行して、手順に従います
3. バージョンを確認します：

node --version
npm --version

使用方法

サーバーを実行する前に、TypeScript プロジェクトをビルドする必要があります。

npm install
npm run build

使用する WSL ディストリビューション（任意）と公開するディレクトリを指定して、サーバーを実行します。

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

ディストリビューションを指定しない場合は、既定の WSL ディストリビューションが使用されます。

例

Ubuntu-20.04 ディストリビューションにアクセスします。

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

既定のディストリビューションを使用します。

node dist/index.js /home/user/documents

Claude Desktop での使用方法

これを claude_desktop_config.json に追加します。

オプション 1：特定の WSL ディストリビューションを使用する

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

オプション 2：既定の WSL ディストリビューションを使用する

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

2 つ目の例では、ディストリビューションを指定しなくても、システムが既定の WSL ディストリビューションを使用します。

元のプロジェクトとの違い

このフォークでは、元の Filesystem MCP Server を WSL で動作するように、次のように調整しています。

1. Node.js のファイルシステムへの直接呼び出しを、WSL コマンドの実行に置き換えています
2. 特定の WSL ディストリビューションを選択できるようにしています
3. Windows 形式と Linux 形式のパス変換を実装しています
4. クロスプラットフォーム互換性のために、ファイルの内容の処理を強化しています
5. WSL 管理用の専用ツールを追加しています

ライセンス

このプロジェクトは、Model Context Protocol チームが作成した元のFilesystem MCP Serverのフォークです。

この WSL 用 MCP サーバーは、元のプロジェクトのライセンスに従い、MIT License の下でライセンスされています。MIT License の利用規約に従う限り、ソフトウェアを自由に使用、変更、配布できます。詳しくは、元のプロジェクトリポジトリにある LICENSE ファイルをご覧ください。