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

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

機能

ファイルの読み取り/書き込み
ディレクトリの作成/一覧表示/削除
ファイル/ディレクトリの移動
ファイルの検索
ファイルメタデータの取得
Roots による動的ディレクトリアクセス制御

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

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

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

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

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

方法2: MCP Roots（推奨）

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

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

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

この方法は推奨されます。これにより、サーバーを再起動することなく roots/list_changed 通知を介してランタイム時にディレクトリを更新でき、より柔軟でモダンな統合体験を提供します。

動作の仕組み

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

サーバー起動
- サーバーはコマンドライン引数で指定されたディレクトリで起動します（指定がある場合）
- 引数が指定されていない場合、サーバーは空の許可ディレクトリで起動します
クライアント接続と初期化
- クライアントが接続し、initialize リクエストを機能とともに送信します
- サーバーはクライアントがrootsプロトコルをサポートしているかどうかを確認します（capabilities.roots）
Rootsプロトコルの処理（クライアントがrootsをサポートする場合）
- 初期化時: サーバーは roots/list を介してクライアントにrootsを要求します
- クライアントは設定されたrootsで応答します
- サーバーはすべての許可ディレクトリをクライアントのrootsで置き換えます
- ランタイム更新時: クライアントは notifications/roots/list_changed を送信できます
- サーバーは更新されたrootsを要求し、許可ディレクトリを再度置き換えます
フォールバック動作（クライアントがrootsをサポートしない場合）
- サーバーはコマンドライン引数で指定されたディレクトリのみを使用し続けます
- 動的な更新はできません
アクセス制御
- すべてのファイルシステム操作は許可ディレクトリ内に制限されます
- list_allowed_directories ツールを使用して現在のディレクトリを確認できます
- サーバーが動作するには、少なくとも1つの許可ディレクトリが必要です

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

API

ツール

read_text_file
- ファイルの内容全体をテキストとして読み取ります
- 入力:
  - path (string)
  - head (number, オプション): 最初のN行
  - tail (number, オプション): 最後のN行
- 拡張子に関係なくファイルを常にUTF-8テキストとして扱います
- head と tail を同時に指定することはできません
read_media_file
- 画像または音声ファイルを読み取ります
- 入力:
  - path (string)
- ファイルをストリーミングし、対応するMIMEタイプとともにbase64データを返します
read_multiple_files
- 複数のファイルを同時に読み取ります
- 入力: paths (string[])
- 読み取りに失敗しても全体の操作は停止しません
write_file
- 新しいファイルを作成するか、既存のファイルを上書きします（注意して使用してください）
- 入力:
  - path (string): ファイルの場所
  - content (string): ファイルの内容
edit_file
- 高度なパターンマッチングと書式設定を使用して選択的な編集を行います
- 機能:
  - 行ベースおよび複数行のコンテンツマッチング
  - インデント保持による空白の正規化
  - 位置を正しく調整した複数同時編集
  - インデントスタイルの検出と保持
  - コンテキスト付きの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, オプション): エントリを "name" または "size" で並べ替え（デフォルト: "name"）
- ファイルサイズと統計情報を含む詳細な一覧を返します
- ファイル数、ディレクトリ数、合計サイズを表示します
move_file
- ファイルとディレクトリを移動または名前変更します
- 入力:
  - source (string)
  - destination (string)
- 移動先が存在する場合は失敗します
search_files
- パターンに一致する、または一致しないファイル/ディレクトリを再帰的に検索します
- 入力:
  - path (string): 開始ディレクトリ
  - pattern (string): 検索パターン
  - excludePatterns (string[]): 除外するパターン
- グロブスタイルのパターンマッチング
- 一致したファイルの完全パスを返します
directory_tree
- ディレクトリ内容の再帰的なJSONツリー構造を取得します
- 入力:
  - path (string): 開始ディレクトリ
  - excludePatterns (string[]): 除外するパターン。グロブ形式がサポートされています
- 戻り値:
  - JSON配列。各エントリには以下が含まれます:
    - name (string): ファイル/ディレクトリ名
    - type ('file'|'directory'): エントリのタイプ
    - children (array): ディレクトリの場合のみ存在
      - 空のディレクトリの場合は空の配列
      - ファイルの場合は省略
- 出力は読みやすさのために2スペースインデントでフォーマットされます
get_file_info
- ファイル/ディレクトリの詳細メタデータを取得します
- 入力: path (string)
- 戻り値:
  - サイズ
  - 作成時間
  - 変更時間
  - アクセス時間
  - タイプ（ファイル/ディレクトリ）
  - パーミッション
list_allowed_directories
- サーバーがアクセスを許可されているすべてのディレクトリを一覧表示します
- 入力不要
- 戻り値:
  - このサーバーが読み取り/書き込みできるディレクトリ

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

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

読み取り専用ツールと書き込み可能ツールを区別する
どの書き込み操作が冪等であるか（同じ引数で再試行しても安全）を理解する
破壊的な可能性がある操作（データの上書きや大幅な変更）を強調表示する

ファイルシステムツールのマッピングは次のとおりです:

ツール	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 の場合にのみ意味を持ちます。

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",
        "${wor…

[翻訳のため省略]

DrDexter6000/talking-cli

talking-cli とは？

お気に入りのAIに質問する

プレビュー

ドキュメント

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

機能

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

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

方法2: MCP Roots（推奨）

動作の仕組み

API

ツール

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

Claude Desktopでの使用

Docker

NPX

VS Codeでの使用

Docker

NPX

関連スキル

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep