Filesystem MCP Server

Filesystem MCP Server

ファイルシステム操作のための、安全な単一バイナリの MCP サーバーです。実行時の依存関係はありません。ダウンロードして、許可するディレクトリを設定し、任意の MCP クライアントに接続するだけです。

ファイル編集、コードベースの検索、リファクタリング、複数ファイルの一括操作など、実際のコーディングワークフローで Claude Desktop および Claude Code を使って広範にテストされています。

このサーバーを選ぶ理由

• 単一バイナリ — Node.js、Python、その他の実行環境は不要です。ダウンロードして実行できます
• 実際の AI ワークフローでテスト済み — 日々のコーディングタスクで Claude Desktop および Claude Code を使って実運用を重ねています
• 18 個のツール — 基本的な読み書きにとどまらず、正規表現検索、パターンに基づく置換、自動インデント付きのコード挿入、一括操作に対応しています
• ドライランプレビュー — 置換ツールや挿入ツールで、適用前に変更内容をプレビューできます
• デフォルトで安全 — 設定済みディレクトリ内にサンドボックス化され、シンボリックリンク攻撃の防止とパストラバーサル対策を備えています
• 詳細なエラーメッセージ — アクセスが拒否された場合、エラーの理由と修正方法が表示されます

インストール

リリースバイナリをダウンロード

Releases ページから、お使いのプラットフォーム用の最新バイナリをダウンロードしてください。

プラットフォーム	バイナリ
macOS（Apple Silicon）	filesystem-mcp-darwin-arm64
macOS（Intel）	filesystem-mcp-darwin-amd64
Linux（x86_64）	filesystem-mcp-linux-amd64
Linux（ARM64）	filesystem-mcp-linux-arm64
Windows	filesystem-mcp-windows-amd64.exe

実行可能にします（macOS/Linux）。

chmod +x filesystem-mcp-darwin-arm64

ソースからビルド

go build -ldflags="-s -w" -o bin/filesystem-mcp ./cmd

設定

環境変数を使って許可するディレクトリを設定します。

export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"

ツール

読み取り

• read_file — 1 つのファイルを読み取ります。部分的に読み取る場合は、start_line／end_line を指定できます
• read_multiple_files — 1 回の呼び出しで複数のファイルを同時に読み取ります
• search_in_files — ファイルを再帰的に検索する正規表現検索です。ファイルパス、行番号、一致したテキストを返します。バイナリファイルは自動的にスキップします。パラメーター：path、pattern、file_extensions、max_results、case_sensitive

書き込み

• write_file — ファイルを作成または上書きします。親ディレクトリも自動的に作成します
• append_to_file — ファイルの末尾に内容を追加します。ファイルが存在しない場合は作成します
• prepend_to_file — ファイルの先頭に内容を追加します。ファイルが存在しない場合は作成します

テキスト置換

すべての置換ツールで dry_run に対応しており、変更を適用せずにプレビューできます。

• replace_in_file — ファイル内の完全一致する文字列を置換します。パラメーター：path、search、replace、occurrence（0＝すべて）、dry_run
• replace_in_file_regex — キャプチャグループ（$1、$2）に対応し、正規表現パターンに一致する箇所を置換します。パラメーター：path、pattern、replace、occurrence、case_sensitive、dry_run
• replace_in_files — 複数のファイルにわたって文字列を一括置換します。適用前にすべてのパスを検証します。パラメーター：paths、search、replace、dry_run

正規表現に基づく挿入

すべての挿入ツールで dry_run と autoIndent（周囲のインデントに合わせる）に対応しています。

• insert_after_regex — 正規表現パターンに一致する箇所の後に内容を挿入します。パラメーター：path、pattern、content、occurrence（0＝すべて、デフォルトは 1）、autoIndent、dry_run
• insert_before_regex — 正規表現パターンに一致する箇所の前に内容を挿入します。上記と同じパラメーターです

行のコピー

• copy_lines — コンテキストのオーバーヘッドなしで、ソースファイルの指定行範囲をディスク上で直接コピー先ファイルにコピーします。パラメーター：source_path、destination_path、start_line、end_line、append

ディレクトリ操作

• list_directory — パターン、ファイルの種類、再帰の深さ、隠しファイル、メタデータで絞り込んでディレクトリの内容を一覧表示します。パラメーター：path、pattern、file_type、recursive、max_depth、max_results、include_hidden、include_metadata
• create_directory — ディレクトリと親ディレクトリを作成します（冪等）
• list_allowed_directories — アクセス可能なディレクトリを表示します

ファイル管理

• move_file — ファイルとディレクトリを移動または名前変更します
• get_file_info — ファイルのメタデータ（サイズ、権限、更新日時）を取得します

Claude Desktop での使用

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp-darwin-arm64",
      "env": {
        "MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
      }
    }
  }
}

セキュリティ

このサーバーは、不正なファイルアクセスを防ぐため、多層防御のセキュリティを実装しています。

パスの検証

• シンボリックリンクの解決：検証前に、すべてのパスを filepath.EvalSymlinks() によって正規形式に解決します
• パストラバーサルの防止：../ による脱出の試みをブロックします
• プレフィックス照合の保護：パス区切り文字を使って検証し、/allowed が /allowed_attacker と一致するのを防ぎます

シンボリックリンクの処理

• 許可されたディレクトリ内にあるシンボリックリンクは、そのリンク先も許可されたディレクトリ内にある場合に許可されます
• 許可されたディレクトリの外を指すシンボリックリンクはブロックされます
• リンク切れのシンボリックリンクは拒否されます
• 許可されたディレクトリ自体はシンボリックリンクでも構いません（初期化時に解決されます）

書き込み操作のセキュリティ

• 新しいファイルを作成する際、親ディレクトリの階層を検証します
• パスの解決と検証はアトミックに実行されます

セキュリティログ

• ブロックされたアクセスの試みはすべて、SECURITY: プレフィックスを付けて記録されます
• ログには、要求されたパスとその正規化された解決先の両方が含まれます

ベストプラクティス

• MCP_ALLOWED_DIRS には必要最小限のディレクトリを設定します
• 許可するディレクトリには絶対パスを使用します
• SECURITY: メッセージがないかログを監視します

ライセンス

MIT ライセンス