Filesystem

Filesystem MCP サーバー

ファイルシステム操作を行う Model Context Protocol（MCP）を実装した Node.js サーバーです。

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

機能

• ファイルの読み取り／書き込み
• ディレクトリの作成／一覧表示／削除
• ファイル／ディレクトリの移動
• ファイルの検索
• ファイルのメタデータの取得
• コマンドライン引数によるディレクトリアクセス制御。Roots は非推奨で、2025 年代の便利機能として利用できます
• stdio で両方のプロトコル世代に対応：2026-07-28 のクライアント（server/discover、ハンドシェイクなし）と、2025 年代のクライアント（initialize）

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

サーバーがアクセスできるのは、許可されたディレクトリのみです。コマンドラインで指定してください。Roots に対応した 2025 年代のクライアントは、実行時にこれらのディレクトリを置き換えることもできます。ただし、Roots はプロトコルバージョン 2026-07-28 で非推奨となっており、2026-07-28 の接続では使用できません。

方法 1：コマンドライン引数（推奨）

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

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

すべてのプロトコルバージョンで機能するのはこの方法だけなので、こちらを使用してください。

方法 2：MCP Roots（非推奨、2025 年代のクライアントのみ）

2025 年代のプロトコルバージョン（initialize ハンドシェイク）で接続し、Roots に対応したクライアントは、許可するディレクトリを動的に更新できます。

クライアントからサーバーに通知された Roots は、指定されている場合、サーバー側の許可されたディレクトリをすべて置き換えます。

重要：サーバーをコマンドライン引数なしで起動し、2025 年代のクライアントが roots プロトコルに対応していない場合、サーバーは初期化時に失敗します。理由を stderr に記録し、接続を閉じてステータス 1 で終了します。Roots に対応したクライアントが Roots を提供しない（または有効な Roots を一つも提供しない）場合、接続は維持されますが、有効な Roots を含む roots/list_changed が送信されるまで、許可されたディレクトリはありません。

2026-07-28 のプロトコルには initialize ハンドシェイクもサーバーからクライアントへの roots/list リクエストもありません。そのため、2026-07-28 のクライアントの Roots が要求されることはなく、コマンドラインで指定したディレクトリが許可リストのすべてです。ディレクトリを一つも指定せずにサーバーを起動した場合、そのような接続でのすべてのツール呼び出しに対し、その旨を示すエラーを返します。

仕組み

サーバーのディレクトリアクセス制御は、次の流れで行われます。

1. サーバーの起動

   • サーバーは、コマンドライン引数で指定されたディレクトリがあれば、それを使用して起動します
   • 引数が指定されていない場合、サーバーは許可されたディレクトリが空の状態で起動します

2. クライアントの接続

   • クライアントからの最初のメッセージによって、接続で使用するプロトコルの世代が決まります
   • 2026-07-28 クライアントは server/discover（またはリクエストごとの _meta エンベロープを含む任意のリクエスト）を送信します。サーバーはコマンドラインで指定されたディレクトリを使用し、手順3と4は適用されません
   • 2025-era クライアントは自身の機能を含む initialize を送信し、サーバーは roots をサポートしているかどうか（capabilities.roots）を確認します

3. Roots プロトコルの処理（roots をサポートする 2025-era クライアント）

   • 初期化時：サーバーは roots/list を使ってクライアントに roots を要求します
   • クライアントは設定済みの roots を返します
   • サーバーは許可されたディレクトリをすべてクライアントの roots に置き換えます
   • 最初の roots が読み込まれる前に届いたツール呼び出しは、クライアントの roots に照らして確認されるよう、roots の読み込みが終わるまで待機します
   • 実行中の更新時：クライアントは notifications/roots/list_changed を送信できます
   • サーバーは更新された roots を要求し、許可されたディレクトリを再び置き換えます
   • 更新の取得中に届いたツール呼び出しは、クライアントが直前に取り消した root に対して実行されないよう、取得が終わるまで待機します
   • クライアントの roots が有効になった後に、有効な roots がない状態で更新されると、アクセスは取り消されます。クライアントが再び root を公開するまで、すべてのパスが拒否されます（「アクセス拒否 - 許可されたディレクトリがありません」）。root が一度も有効になっていない場合、そのような更新を受けてもコマンドラインで指定されたディレクトリが維持されます

4. フォールバック動作（roots をサポートしない 2025-era クライアント）

   • サーバーはコマンドラインで指定されたディレクトリのみを引き続き使用します
   • 動的な更新はできません
   • コマンドラインでディレクトリも指定されていない場合、サーバーはエラーを記録し、接続を閉じてステータス1で終了します

5. アクセス制御

   • すべてのファイルシステム操作は、許可されたディレクトリ内に制限されます
   • 現在のディレクトリを確認するには list_allowed_directories ツールを使用します
   • サーバーが動作するには、少なくとも1つの許可されたディレクトリが必要です

注：サーバーが操作を許可するのは、args で指定されたディレクトリ内、または 2025-era クライアントの場合は Roots 経由で指定されたディレクトリ内のみです。

API

ツール

• read_text_file

  • ファイルの内容全体をテキストとして読み込みます
  • 入力：
    • path（文字列）
    • head（数値、任意）：先頭からN行
    • tail（数値、任意）：末尾からN行
  • 拡張子にかかわらず、常にファイルをUTF-8テキストとして扱います
  • head と tail を同時に指定することはできません

• read_media_file

  • ファイルを読み込み、MIMEタイプを含むBase64エンコード済みのコンテンツブロックとして返します
  • 入力：
    • path（文字列）
  • ファイルをストリーミングし、対応するMIMEタイプとともにBase64データを返します。画像ファイルと音声ファイルは image／audio コンテンツとして返されます。それ以外のファイル形式は埋め込み resource（任意のバイナリデータに対応する有効なMCPコンテンツブロック）として返されます

• read_multiple_files

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

• write_file

  • 新しいファイルを作成するか、既存のファイルを上書きします（慎重に使用してください）
  • 入力：
    • path（文字列）：ファイルの場所
    • content（文字列）：ファイルの内容
  • 既存のファイルはその場で上書きされるため、inode、作成日時、ハードリンク、アクセス許可は維持されます（edit_file も同じ方法で書き込みます）。上書きはクラッシュに対してアトミックではないため、書き込み中にクラッシュすると、ファイルの一部だけが書き込まれた状態になることがあります。読み取り専用ファイルは置き換えずに拒否されます

• edit_file

  • 高度なパターンマッチングと書式設定を使用して、選択的に編集します
  • 特長：
    • 行単位および複数行のコンテンツマッチング
    • インデントを保持した空白の正規化
    • 複数の編集を同時に行い、位置を正しく調整
    • インデントスタイルの検出と保持：空白のみが異なる場合、置換後の各行には置換対象の行のインデントが適用されます
    • ファイルの改行コード（LF または CRLF）を保持
    • コンテキストを含む Git 形式の差分出力
    • ドライランモードで変更をプレビュー
  • 入力：
    • path (string)：編集するファイル
    • edits (array)：編集操作のリスト
      • oldText (string)：検索するテキスト（部分文字列を指定できます）
      • newText (string)：置換後のテキスト
    • dryRun (boolean)：変更を適用せずにプレビューします（デフォルト：false）
  • ドライランの場合は詳細な差分と一致情報を返し、それ以外の場合は変更を適用します
  • ベストプラクティス：変更を適用する前に、必ず dryRun を使用してプレビューしてください

• create_directory

  • 新しいディレクトリを作成するか、ディレクトリが存在することを確認します
  • 入力：path (string)
  • 必要に応じて親ディレクトリも作成します
  • ディレクトリがすでに存在する場合は、何もせずに成功します

• list_directory

  • [FILE] または [DIR] のプレフィックスを付けてディレクトリの内容を一覧表示します
  • 入力：path (string)

• list_directory_with_sizes

  • [FILE] または [DIR] のプレフィックスを付け、ファイルサイズを含めてディレクトリの内容を一覧表示します
  • 入力：
    • path (string)：一覧表示するディレクトリのパス
    • sortBy (string, optional)：エントリを "name" または "size" で並べ替えます（デフォルト："name"）
  • ファイルサイズと統計の概要を含む詳細な一覧を返します
  • ファイル数、ディレクトリ数、合計サイズを表示します

• move_file

  • ファイルとディレクトリを移動または名前変更します
  • 入力：
    • source (string)
    • destination (string)
  • 移動先がすでに存在する場合は失敗します

• search_files

  • パターンに一致する、または一致しないファイル／ディレクトリを再帰的に検索します
  • 入力：
    • path (string)：検索開始ディレクトリ
    • pattern (string)：検索パターン
    • excludePatterns (string[])：除外するパターン
  • Glob 形式のパターンマッチング
  • 一致した項目の完全なパスを返します

• directory_tree

  • ディレクトリの内容を再帰的な JSON ツリー構造で取得します
  • 入力：
    • path (string)：検索開始ディレクトリ
    • excludePatterns (string[])：除外するパターン。Glob 形式に対応しています
  • 戻り値：
    • 各エントリに以下の内容を含む JSON 配列：
      • name (string)：ファイル／ディレクトリ名
      • type ('file'|'directory')：エントリの種類
      • children (array)：ディレクトリの場合のみ存在します
        • 空のディレクトリの場合は空の配列
        • ファイルの場合は省略
  • 出力は読みやすいように2スペースでインデントされます

• get_file_info

  • ファイル／ディレクトリの詳細なメタデータを取得します
  • 入力：path (string)
  • 戻り値：
    • サイズ
    • 作成日時
    • 更新日時
    • アクセス日時
    • 種類（ファイル／ディレクトリ）
    • 権限

• list_allowed_directories

  • サーバーがアクセスを許可されているすべてのディレクトリを一覧表示します
  • 入力は不要です
  • 戻り値：
    • このサーバーが読み取り／書き込み可能なディレクトリ

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

このサーバーは、各ツールに MCP ToolAnnotations を設定しているため、クライアントは次のことができます。

• 読み取り専用ツールと書き込み可能なツールを区別できます。
• どの書き込み操作が冪等（同じ引数で安全に再試行できる）かを把握できます。
• 破壊的（データを上書きしたり、大幅に変更したりする）可能性のある操作を強調表示できます。
• ツールがオープンな世界や外部の世界にアクセスしないことを示せます（すべてのファイルシステムツールは openWorldHint: false を設定します）。

ファイルシステムツールの対応関係は次のとおりです。

ツール	readOnlyHint	idempotentHint	destructiveHint	備考
read_text_file	true	–	–	読み取りのみ
read_media_file	true	–	–	読み取りのみ
read_multiple_files	true	–	–	読み取りのみ
list_directory	true	–	–	読み取りのみ
list_directory_with_sizes	true	–	–	読み取りのみ
directory_tree	true	–	–	読み取りのみ
search_files	true	–	–	読み取りのみ
get_file_info	true	–	–	読み取りのみ
list_allowed_directories	true	–	–	読み取りのみ
create_directory	false	true	false	同じディレクトリを再作成しても何も起こりません
write_file	false	true	true	既存ファイルを上書きします
edit_file	false	false	true	編集を再適用すると失敗したり、二重に適用されたりすることがあります
move_file	false	false	true	元のファイルを削除します

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

要件

サーバーを npx 経由またはソースから実行する場合、Node.js 24 以降が必要です。

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 では、npx を起動するために cmd /c を使用します。

{
  "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 ファイルを参照してください。