Filesystem MCP Server

ファイルシステム操作のためのModel Context Protocol (MCP)を実装したNode.jsサーバー。

npmに@modelcontextprotocol/server-filesystemとして公開されています。

機能

• ファイルの読み書き

• ディレクトリの作成/一覧表示/削除

• ファイル/ディレクトリの移動

• ファイルの検索

• ファイルメタデータの取得

• Rootsによる動的ディレクトリアクセス制御

ディレクトリアクセス制御

サーバーは柔軟なディレクトリアクセス制御システムを採用しています。ディレクトリはコマンドライン引数で指定するか、Rootsを介して動的に指定できます。

方法1: コマンドライン引数

サーバー起動時に許可ディレクトリを指定します。

mcp-server-filesystem /path/to/dir1 /path/to/dir2

方法2: MCP Roots (推奨)

RootsをサポートするMCPクライアントは、許可ディレクトリを動的に更新できます。

クライアントからサーバーに通知されるRootsは、サーバー側の許可ディレクトリを完全に置き換えます。

重要: サーバーがコマンドライン引数なしで起動し、かつクライアントがRootsプロトコルをサポートしていない（または空のRootsを提供する）場合、サーバーは初期化中にエラーをスローします。

この方法を推奨します。roots/list_changed通知によりサーバー再起動なしでディレクトリを動的に更新できるため、より柔軟でモダンな統合体験を提供します。

動作の仕組み

サーバーのディレクトリアクセス制御は以下のフローに従います。

1. サーバー起動

   • サーバーはコマンドライン引数で指定されたディレクトリで起動する（指定された場合）

   • 引数がない場合、サーバーは空の許可ディレクトリで起動する

2. クライアント接続と初期化

   • クライアントが接続し、initializeリクエストと機能を送信する

   • サーバーはクライアントがRootsプロトコルをサポートしているか確認する（capabilities.roots）

3. Rootsプロトコル処理（クライアントがRootsをサポートする場合）

   • 初期化時: サーバーはroots/listでクライアントにRootsを要求する

   • クライアントは設定済みのRootsで応答する

   • サーバーはすべての許可ディレクトリをクライアントのRootsで置き換える

   • 実行時更新: クライアントはnotifications/roots/list_changedを送信できる

   • サーバーは更新されたRootsを要求し、再び許可ディレクトリを置き換える

4. フォールバック動作（クライアントがRootsをサポートしない場合）

   • サーバーはコマンドラインのディレクトリのみを使用し続ける

   • 動的な更新は不可

5. アクセス制御

   • すべてのファイルシステム操作は許可ディレクトリ内に制限される

   • list_allowed_directoriesツールを使用して現在のディレクトリを確認できる

   • サーバーは動作に少なくとも1つの許可ディレクトリが必要

注意: サーバーはargsまたはRootsで指定されたディレクトリ内でのみ操作を許可します。

API

ツール

• read_text_file

  • ファイルの内容をテキストとして完全に読み取る

  • 入力:

    • path (文字列)

    • head (数値, オプション): 最初のN行

    • tail (数値, オプション): 最後のN行

  • 拡張子に関わらず常にUTF-8テキストとして扱う

  • headとtailを同時に指定することはできない

• read_media_file

  • ファイルを読み取り、base64エンコードされたコンテンツブロックとMIMEタイプとして返す

  • 入力:

    • path (文字列)

  • ファイルをストリームし、base64データと対応するMIMEタイプを返す。画像とオーディオファイルはimage/audioコンテンツとして返され、その他のファイルタイプは埋め込みresource（任意のバイナリデータに対する有効なMCPコンテンツブロック）として返される

• read_multiple_files

  • 複数のファイルを同時に読み取る

  • 入力: paths (文字列[])

  • 読み取りに失敗しても全体の操作は停止しない

• write_file

  • 新しいファイルを作成するか、既存のファイルを上書きする（注意して使用すること）

  • 入力:

    • path (文字列): ファイルの場所

    • content (文字列): ファイルの内容

• edit_file

  • 高度なパターンマッチングとフォーマットを使用して選択的に編集する

  • 機能:

    • 行ベースおよび複数行のコンテンツマッチング

    • インデント保持による空白の正規化

    • 正しい位置を考慮した複数の同時編集

    • インデントスタイルの検出と保持

    • コンテキスト付きGit形式の差分出力

    • ドライランモードで変更をプレビュー

  • 入力:

    • path (文字列): 編集するファイル

    • edits (配列): 編集操作のリスト

      • oldText (文字列): 検索するテキスト（部分文字列可）

      • newText (文字列): 置換するテキスト

    • dryRun (ブール値): 適用せずに変更をプレビュー（デフォルト: false）

  • ドライランでは詳細な差分とマッチ情報を返し、それ以外は変更を適用する

  • ベストプラクティス: 変更を適用する前に必ずdryRunを使用してプレビューすること

• create_directory

  • 新しいディレクトリを作成するか、存在することを確認する

  • 入力: path (文字列)

  • 必要に応じて親ディレクトリも作成する

  • ディレクトリが存在する場合は静かに成功する

• list_directory

  • ディレクトリの内容を[FILE]または[DIR]プレフィックス付きで一覧表示する

  • 入力: path (文字列)

• list_directory_with_sizes

  • ディレクトリの内容を[FILE]または[DIR]プレフィックス付きで、ファイルサイズを含めて一覧表示する

  • 入力:

    • path (文字列): 一覧表示するディレクトリパス

    • sortBy (文字列, オプション): "name"または"size"でエントリをソート（デフォルト: "name"）

  • ファイルサイズと集計統計を含む詳細な一覧を返す

  • ファイル数、ディレクトリ数、合計サイズを表示

• move_file

  • ファイルやディレクトリを移動または名前変更する

  • 入力:

    • source (文字列)

    • destination (文字列)

  • 移動先が存在する場合は失敗する

• search_files

  • パターンに一致する（または一致しない）ファイル/ディレクトリを再帰的に検索する

  • 入力:

    • path (文字列): 開始ディレクトリ

    • pattern (文字列): 検索パターン

    • excludePatterns (文字列[]): 除外するパターン

  • グロブスタイルのパターンマッチング

  • 一致したファイルのフルパスを返す

• directory_tree

  • ディレクトリ内容の再帰的なJSONツリー構造を取得する

  • 入力:

    • path (文字列): 開始ディレクトリ

    • excludePatterns (文字列[]): 除外するパターン。グロブ形式がサポートされます

  • 戻り値:

    • JSON配列。各エントリに以下を含む:

      • name (文字列): ファイル/ディレクトリ名

      • type ('file'|'directory'): エントリタイプ

      • children (配列): ディレクトリの場合のみ存在

        • 空ディレクトリの場合は空配列

        • ファイルの場合は省略

  • 出力は読みやすさのため2スペースインデントでフォーマットされる

• get_file_info

  • ファイル/ディレクトリの詳細なメタデータを取得する

  • 入力: path (文字列)

  • 戻り値:

    • サイズ

    • 作成時刻

    • 変更時刻

    • アクセス時刻

    • タイプ（ファイル/ディレクトリ）

    • パーミッション

• list_allowed_directories

  • サーバーがアクセスを許可されているすべてのディレクトリを一覧表示する

  • 入力不要

  • 戻り値:

    • このサーバーが読み書きできるディレクトリ

ツールアノテーション（MCPヒント）

このサーバーは各ツールにMCP ToolAnnotationsを設定し、クライアントが以下を識別できるようにします:

• 読み取り専用ツールと書き込み可能ツールを区別する

• どの書き込み操作がべき等（同じ引数で再試行しても安全）かを理解する

• 破壊的（データの上書きや大幅な変更）な操作を強調表示する

• ツールがオープンまたは外部の世界に到達しないことを示す（すべてのファイルシステムツールはopenWorldHint: falseを設定します）

ファイルシステムツールのマッピングは以下の通りです:

注: MCP仕様で定義されている通り、idempotentHintとdestructiveHintはreadOnlyHintがfalseの場合にのみ意味を持ちます。すべてのツールはopenWorldHint: falseも設定します。このサーバーは許可ディレクトリ内のローカルファイルシステムにのみアクセスし、オープンまたは外部の世界には決してアクセスしません。

Claude Desktopでの使用

claude_desktop_config.jsonに以下を追加してください:

注: サンドボックス化されたディレクトリを/projectsにマウントしてサーバーに提供できます。roフラグを追加すると、そのディレクトリはサーバーから読み取り専用になります。

Docker

注: すべてのディレクトリはデフォルトで/projectsにマウントする必要があります。

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Windowsでは、cmd /cを使用してnpxを起動します:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

VS Codeでの使用

クイックインストールには、以下のインストールボタンをクリックしてください...

手動インストールの場合は、以下のいずれかの方法でMCPサーバーを設定できます。

方法1: ユーザー設定（推奨） ユーザーレベルのMCP設定ファイルに設定を追加します。コマンドパレット（Ctrl + Shift + P）を開き、MCP: Open User Configuration を実行します。これにより、ユーザーのmcp.jsonファイルが開き、サーバー設定を追加できます。

方法2: ワークスペース設定 あるいは、ワークスペース内の.vscode/mcp.jsonというファイルに設定を追加することもできます。これにより、他のユーザーと設定を共有できます。

VS CodeでのMCP設定の詳細については、公式VS Code MCPドキュメントを参照してください。

サーバーにサンドボックス化されたディレクトリを提供するには、それらを/projectsにマウントします。roフラグを追加すると、サーバーからディレクトリが読み取り専用になります。

Docker

注：デフォルトでは、すべてのディレクトリを/projectsにマウントする必要があります。

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Windowsでは、以下を使用します：

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

ビルド

Dockerビルド：

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

ライセンス

このMCPサーバーはMITライセンスの下でライセンスされています。これは、MITライセンスの条項と条件に従い、ソフトウェアを自由に使用、変更、配布できることを意味します。詳細については、プロジェクトリポジトリ内のLICENSEファイルを参照してください。