ファイルシステムMCPサーバー

包括的な権限制御と強化された機能を備えたファイルシステム操作用のモデルコンテキストプロトコル (MCP) を実装する Node.js サーバー。

特徴

きめ細かな権限制御（読み取り専用、フルアクセス、または特定の操作権限）
許可されたディレクトリ内での安全なファイル操作
ファイル操作:
- ファイルの読み取り/書き込み/変更
- ディレクトリの作成/一覧表示/削除
- ファイル/ディレクトリを移動する
- 名前または拡張子でファイルを検索する
- ファイルのメタデータを取得する
ディレクトリ操作:
- ディレクトリ構造のツリービュー
- 除外パターンを使用した再帰操作
ユーティリティ関数:
- XMLからJSONへの変換
- 1回の呼び出しで複数のファイル操作
- パターンマッチングによる高度なファイル編集
セキュリティ機能:
- シンボリックリンク制御
- パス検証
- サンドボックス化された操作

注意: サーバーは、設定された権限に従って、 argsで指定されたディレクトリ内でのみ操作を許可します。

API

リソース

file://system : ファイルシステム操作インターフェース

ツール

読み取りファイル
- ファイルの完全な内容を読み取る
- 入力: path (文字列)
- UTF-8エンコードでファイル内容全体を読み取ります
複数のファイルを読み取る
- 複数のファイルを同時に読み取る
- 入力: paths (文字列[])
- 読み取りに失敗しても操作全体が停止することはない
ファイルの作成
- コンテンツを含む新しいファイルを作成する
- 入力:
  - path （文字列）: ファイルの場所
  - content (文字列): ファイルの内容
- ファイルが既に存在する場合は失敗します
- create権限が必要です
ファイルの変更
- 既存のファイルを新しいコンテンツで変更する
- 入力:
  - path （文字列）: ファイルの場所
  - content (文字列): 新しいファイルの内容
- ファイルが存在しない場合は失敗します
- edit権限が必要です
編集ファイル
- パターンマッチングと書式設定を使用して選択的な編集を行う
- 特徴：
  - 行ベースおよび複数行のコンテンツマッチング
  - インデントを保持した空白の正規化
  - 正しい位置で複数の編集を同時に行う
  - インデントスタイルの検出と保存
  - コンテキスト付きのGitスタイルのdiff出力
  - ドライランモードで変更をプレビューする
- 入力:
  - path （文字列）：編集するファイル
  - edits （配列）：編集操作のリスト
    - oldText (文字列): 検索するテキスト（完全一致）
    - newText (文字列): 置換するテキスト
  - dryRun (ブール値): 変更を適用せずにプレビューします (デフォルト: false)
- ドライランの詳細な差分を返し、それ以外の場合は変更を適用します
- edit権限が必要です
- ベストプラクティス: 変更をプレビューするには、必ず最初に dryRun を使用してください。
ディレクトリの作成
- 新しいディレクトリを作成するか、存在することを確認します
- 入力: path (文字列)
- 必要に応じて親ディレクトリを作成します
- ディレクトリが存在する場合は、何もせずに成功します
- create権限が必要です
リストディレクトリ
- [FILE]または[DIR]プレフィックスを持つディレクトリの内容を一覧表示します
- 入力: path (文字列)
- ファイルとディレクトリの詳細なリストを返します
ディレクトリツリー
- ディレクトリ構造の再帰ツリービューを取得する
- 入力: path (文字列)
- ファイルとディレクトリを含むJSON構造を返します
- 各エントリには、名前、タイプ、子（ディレクトリの場合）が含まれます。
ファイルの移行
- ファイルとディレクトリの移動または名前の変更
- 入力:
  - source (文字列): ソースパス
  - destination (文字列): 宛先パス
- 宛先が存在する場合は失敗します
- ファイルとディレクトリの両方で動作します
- move権限が必要です
ファイルを削除
- ファイルを削除する
- 入力: path (文字列)
- ファイルが存在しない場合は失敗します
- delete権限が必要です
ディレクトリの削除
- ディレクトリを削除する
- 入力:
  - path (文字列): 削除するディレクトリ
  - recursive (boolean): コンテンツを削除するかどうか (デフォルト: false)
- ディレクトリが空でなく、再帰が偽の場合、失敗します
- delete権限が必要です
検索ファイル
- ファイル/ディレクトリを再帰的に検索する
- 入力:
  - path （文字列）：開始ディレクトリ
  - pattern (文字列): 検索パターン
  - excludePatterns (string[]): 除外パターン（glob形式をサポート）
- 大文字と小文字を区別しないマッチング
- 一致するフルパスを返します
拡張子でファイルを検索する
- 特定の拡張子を持つすべてのファイルを検索する
- 入力:
  - path （文字列）：開始ディレクトリ
  - extension （文字列）：検索するファイル拡張子
  - excludePatterns (string[]): オプションの除外パターン
- 大文字と小文字を区別しない拡張子のマッチング
- 一致するファイルへのフルパスを返します
ファイル情報を取得する
- 詳細なファイル/ディレクトリのメタデータを取得する
- 入力: path (文字列)
- 戻り値:
  - サイズ
  - 作成時間
  - 修正時間
  - アクセス時間
  - タイプ（ファイル/ディレクトリ）
  - 権限
権限の取得
- 現在のサーバー権限を取得する
- 入力不要
- 戻り値:
  - 権限フラグ（読み取り専用、フルアクセス、作成、編集、移動、削除）
  - シンボリックリンクのフォローステータス
  - 許可されるディレクトリの数
許可されたディレクトリの一覧
- サーバーがアクセスを許可されているすべてのディレクトリを一覧表示します
- 入力不要
- 許可されたディレクトリパスの配列を返します
XMLからJSONへ
- XMLファイルをJSON形式に変換する
- 入力:
  - xmlPath (文字列): ソースXMLファイル
  - jsonPath (文字列): 宛先JSONファイル
  - options (オブジェクト): オプション設定
    - ignoreAttributes (ブール値): XML属性をスキップします（デフォルト: false）
    - preserveOrder (boolean): プロパティの順序を維持する (デフォルト: true)
    - format （ブール値）：JSONをきれいに印刷する（デフォルト：true）
    - indentSize (数値): JSONインデント(デフォルト: 2)
- XMLファイルのread権限が必要です
- JSONファイルのcreateまたはedit権限が必要です
xml_to_json_string
- XMLファイルをJSON文字列に変換する
- 入力:
  - xmlPath (文字列): ソースXMLファイル
  - options (オブジェクト): オプション設定
    - ignoreAttributes (ブール値): XML属性をスキップします（デフォルト: false）
    - preserveOrder (boolean): プロパティの順序を維持する (デフォルト: true)
- XMLファイルのread権限が必要です
- JSON文字列表現を返す
xml_クエリ
- XPath式を使用してXMLファイルをクエリする
- 入力:
  - path (文字列): XMLファイルへのパス
  - query (文字列、オプション): 実行するXPathクエリ
  - structureOnly （ブール値、オプション）：タグ構造のみを返す
  - maxBytes （数値、オプション）：読み取る最大バイト数（デフォルト：1MB）
  - includeAttributes (ブール値、オプション): 属性情報を含める (デフォルト: true)
- XPath の例:
  - すべての要素を取得: //tagname
  - 特定の属性を持つ要素を取得します: //tagname[@attr="value"]
  - テキストコンテンツを取得: //tagname/text()
- 大きなXMLファイルでもメモリ効率が良い
- クエリ結果または構造のJSON表現を返します
XML構造
- ファイル全体を読み込まずにXML構造を分析
- 入力:
  - path (文字列): XMLファイルへのパス
  - depth （数値、オプション）：分析する深さ（デフォルト：2）
  - includeAttributes (ブール値、オプション): 属性分析を含める
  - maxBytes （数値、オプション）：読み取る最大バイト数（デフォルト：1MB）
- 要素、属性、構造に関する統計情報を返します
- 詳細な分析の前に大規模なXMLファイルを理解するのに便利です

権限とセキュリティ

サーバーは、きめ細かな権限制御を備えた包括的なセキュリティモデルを実装します。

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

操作は、起動時にargsで指定されたディレクトリに厳密に制限されます。
すべての操作（シンボリックリンクのターゲットを含む）は許可されたディレクトリ内でのみ実行する必要があります。
パス検証により、ディレクトリトラバーサルや許可されたパス外へのアクセスが防止されます。

権限フラグ

--readonly : 読み取り専用モードを強制し、他のすべての権限フラグを上書きします
--full-access : すべての操作（作成、編集、移動、削除）を有効にします
個別の権限フラグ (--full-access が設定されていない限り、明示的に有効化する必要があります):
- --allow-create : 新しいファイルとディレクトリの作成を許可する
- --allow-edit : 既存のファイルの変更を許可する
- --allow-move : ファイルとディレクトリの移動/名前変更を許可する
- --allow-delete : ファイルとディレクトリの削除を許可する

デフォルトの動作：権限フラグが指定されていない場合、サーバーは読み取り専用モードで実行されます。書き込み操作を有効にするには、 --full-accessまたは特定の--allow-*フラグを使用する必要があります。

シンボリックリンクの扱い

デフォルトでは、シンボリックリンクがたどられます（リンクとターゲットの両方が許可されたディレクトリ内にある必要があります）
--no-follow-symlinks : シンボリックリンクの追跡を無効にする（操作はリンク自体に対して行われる）

Claude Desktopとカーソルの使用

claude_desktop_config.json (Claude Desktop の場合) または.cursor/mcp.json (Cursor の場合) に適切な構成を追加します。

カーソルの設定

.cursor/mcp.jsonの場合:

{
  "mcpServers": {
    "my-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/path/to/allowed/directory",
        "--full-access"
      ]
    }
  }
}

Dockerの設定

Claude Desktop と Docker の場合:

{
  "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",
        "--readonly",                    // For read-only access
        "--no-follow-symlinks",         // Optional: prevent symlink following
        "/projects"
      ]
    }
  }
}

NPX構成

Claude Desktop または NPX 付き Cursor の場合:

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

許可フラグの例

さまざまな権限の組み合わせでサーバーを構成できます。

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--readonly"                         // Read-only mode
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--full-access",                    // Full read/write access
  "--no-follow-symlinks"              // Don't follow symlinks
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--allow-create",                   // Selective permissions
  "--allow-edit"                      // Only allow creation and editing
]

注意: --readonly他のすべての権限フラグよりも優先され、 --full-access --readonlyが指定されていない限りすべての操作を有効にします。

複数のディレクトリと権限

複数のディレクトリを指定する場合、権限フラグはすべてのディレクトリにグローバルに適用されます。

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/first/directory",                // Both directories have the same
  "~/second/directory",               // permission settings (read-only)
  "--readonly"
]

異なるディレクトリに異なる権限レベルが必要な場合は、複数のサーバー構成を作成します。

{
  "mcpServers": {
    "readonly-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sensitive/directory",
        "--readonly"
      ]
    },
    "writeable-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sandbox/directory",
        "--full-access"
      ]
    }
  }
}

コマンドラインの例

読み取り専用アクセス:

npx -y @modelcontextprotocol/server-filesystem --readonly /path/to/dir

フルアクセス:

npx -y @modelcontextprotocol/server-filesystem --full-access /path/to/dir

特定の権限:

npx -y @modelcontextprotocol/server-filesystem --allow-create --allow-edit /path/to/dir

シンボリックリンクが続きません:

npx -y @modelcontextprotocol/server-filesystem --full-access --no-follow-symlinks /path/to/dir

建てる

Dockerビルド:

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

ライセンス

このMCPサーバーはMITライセンスに基づいてライセンスされています。つまり、MITライセンスの条件に従って、ソフトウェアを自由に使用、改変、配布することができます。詳細については、プロジェクトリポジトリのLICENSEファイルをご覧ください。

Filesystem MCP Server