MCPサーバ - Filesystem

提供: MochiuWiki : SUSE, EC, PCB

概要

Filesystem MCP Server (@modelcontextprotocol/server-filesystem) は、AnthropicがNode.jsで実装したMCPサーバである。
MITライセンスで公開されている。

Model Context Protocol (MCP) を通じて、AIアシスタントにローカルファイルシステムへの安全で制御されたアクセスを提供する。
起動時に許可するディレクトリを明示的に指定することで、AIアシスタントはそのディレクトリ内に限定したファイル操作を実行できる。

Claude Desktop、Claude Code、VS Code、Cursor等の主要なMCPクライアントに対応している。
Windows、MacOS、Linuxに対応する。

主な特徴は以下の通りである。

  • 14個のファイル操作ツールを提供 (読み取り、書き込み、ディレクトリ管理、検索等)
  • 指定ディレクトリ外へのアクセスをブロックするパストラバーサル防止機能
  • Dockerイメージ (mcp/filesystem) による実行にも対応
  • Rootsプロトコルによる実行時のディレクトリ動的更新
  • Dockerの :ro フラグを使用した読み取り専用アクセスの設定が可能



動作要件

前提条件

Filesystem MCP Serverを使用するために必要な前提条件を以下に示す。

  • Node.js v18.0.0以上
    npx コマンドを使用してFilesystem MCP Serverを実行するために必要
  • npx コマンド
    Node.jsに同梱されているため、Node.jsのインストールで利用可能になる。
  • Docker (オプション)
    Dockerを使用してFilesystem MCP Serverを実行する場合に必要



インストール

npxを使用した実行

npx コマンドを使用する場合、インストール不要でFilesystem MCP Serverを直接実行できる。
アクセスを許可するディレクトリへの絶対パスをコマンドライン引数で指定する (複数指定可能)。

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory1 /path/to/allowed/directory2


MCPクライアントの設定ファイルで指定する場合は、後述の各クライアント設定を参照すること。

Dockerを使用した実行

Docker Hubに公式イメージ (mcp/filesystem) が公開されており、Node.jsをインストールせずにFilesystem MCP Serverを実行できる。

以下に示すコマンドを実行することにより、ローカルディレクトリをコンテナ内の /projects にマウントしてサーバを起動する。
:ro フラグを付与することで、読み取り専用アクセスとなる。

docker run -i --rm -v /path/to/local/directory:/projects:ro mcp/filesystem


書き込みアクセスを許可する場合は、:ro フラグを省略する。

docker run -i --rm -v /path/to/local/directory:/projects mcp/filesystem



MCPクライアントの設定

設定ファイルの場所

各MCPクライアントの設定ファイルの場所は以下の通りである。

Claude Desktopの設定ファイルを以下に示す。

  • Linux
    ~/.config/Claude/claude_desktop_config.json
  • MacOS
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


Claude Codeの設定ファイルを以下に示す。

  • ローカルスコープ
    .mcp.json (プロジェクトルート) : claude mcp add コマンドで生成される。
  • ユーザスコープ
    ~/.claude.json (ホームディレクトリ)


VS Codeの設定ファイルを以下に示す。

  • .vscode/mcp.json (プロジェクトルート)


Cursorの設定ファイルを以下に示す。

  • グローバル設定
    ~/.cursor/mcp.json
  • プロジェクト設定
    .cursor/mcp.json


Claude Desktopの設定

claude_desktop_config.json ファイルに以下に示す内容を設定する。

 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory1", "/path/to/allowed/directory2"]
     }
   }
 }


設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。

Claude Codeの設定

Claude Codeでは、claude mcp add コマンドを使用してFilesystem MCP Serverを追加できる。

以下に示すコマンドで、MCPサーバをClaude Codeに登録する。

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory


プロジェクトスコープで設定する場合は、--scope project オプションを追加する。
設定は、.mcp.json ファイルに保存される。

claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory


上記コマンドにより生成される .mcp.json ファイルの内容を以下に示す。

 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
     }
   }
 }


OpenCodeの設定

OpenCodeでは、プロジェクトルートまたはグローバル設定の opencode.json ファイルにMCPサーバを定義する。

設定ファイルの読み込み優先順位は以下の通りである。(後の設定が前の設定にマージされる)

  • グローバル設定
    ~/.config/opencode/opencode.json
  • プロジェクト設定
    プロジェクトルートの opencode.json


opencode.json ファイルに以下の内容を記述して、Filesystem MCP Serverを登録する。

 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "filesystem": {
       "type": "local",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
       "enabled": true
     }
   }
 }


複数のディレクトリへのアクセスを許可する場合は、command 配列にディレクトリパスを追加する。

 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "filesystem": {
       "type": "local",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir1", "/path/to/dir2"],
       "enabled": true
     }
   }
 }


MCPサーバを一時的に無効にする場合は、enabled を false に設定する。

VS Codeの設定

.vscode/mcp.json ファイルに以下に示す内容を設定する。
変数 ${workspaceFolder} を使用することにより、ワークスペースのルートディレクトリを自動的に許可対象に指定できる。

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


Cursorの設定

~/.cursor/mcp.json (グローバル設定) または .cursor/mcp.json (プロジェクト設定) ファイルに以下に示す内容を設定する。

 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
     }
   }
 }


プロジェクトルートのみ参照する場合

.mcp.json / opencode.jsonファイルがあるディレクトリ自体を指すには、相対パス . を指定する。
. は、MCPサーバ起動時のカレントディレクトリ (一般的には、.mcp.json / opencode.jsonファイルがあるプロジェクトルート) を指す。

サブディレクトリに限定する場合は、./src のように指定する。

 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
     }
   }
 }



提供ツール

Filesystem MCP Serverは、ファイル読み取り、ファイル書き込み、ディレクトリ管理、ファイル検索・管理の4カテゴリで合計14個のツールを提供する。

ファイル読み取りツール

下表に、ファイルの内容を読み込むためのツールを示す。

ファイル読み取りツールの一覧
ツール名 説明
read_file 指定したファイルの完全な内容を読み込む。
read_text_file テキストファイルを読み込む。
read_file よりも詳細なエラーメッセージを提供する。
read_media_file 画像やオーディオファイルをBase64エンコードして読み込む。
read_multiple_files 複数のファイルを同時に読み込む。


ファイル書き込みツール

下表に、ファイルの作成・編集を行うためのツールを示す。

ファイル書き込みツールの一覧
ツール名 説明
write_file ファイルを新規作成する。
既存ファイルが存在する場合は上書きする。
edit_file 行ベースの編集を行う。
検索・置換操作に対応し、git形式のdiffを出力する。


ディレクトリ管理ツール

下表に、ディレクトリの作成・参照を行うためのツールを示す。

ディレクトリ管理ツールの一覧
ツール名 説明
create_directory ディレクトリを作成する。
ネストしたディレクトリ構造の作成にも対応する。
list_directory ディレクトリの内容を一覧表示する。
ファイルには [FILE]、ディレクトリには [DIR] のプレフィックスが付与される。
list_directory_with_sizes ファイルサイズを含むディレクトリの内容を一覧表示する。
directory_tree ディレクトリ構造をJSON形式のツリーとして取得する。


ファイル検索・管理ツール

下表に、ファイルの検索・メタデータ取得・移動に関するツールを示す。

ファイル検索・管理ツールの一覧
ツール名 説明
search_files グロブパターンを使用してファイルを再帰的に検索する。
get_file_info ファイルのメタデータを取得する。
取得できる情報: ファイルサイズ、作成日時、更新日時等
move_file ファイルまたはディレクトリを移動する。
ファイル、ディレクトリのリネームにも使用できる。
list_allowed_directories サーバ起動時に許可として設定されたディレクトリの一覧を表示する。



セキュリティ

アクセス制限の仕組み

Filesystem MCP Serverは、起動時に指定したディレクトリのみへのアクセスを許可する設計となっている。
指定ディレクトリ外へのアクセス試行はブロックされる。

主なセキュリティ機能を以下に示す。

  • 指定ディレクトリへのアクセス制限
    サーバ起動時にコマンドライン引数で指定したディレクトリのみにアクセスを限定する。
  • パストラバーサル防止
    ../ 等を利用した許可ディレクトリ外へのアクセスを防止する。
  • Rootsプロトコルによる動的更新
    MCPのRootsプロトコルにより、実行時に許可ディレクトリを動的に更新できる。
  • Docker使用時の読み取り専用設定
    Docker実行時に :ro フラグを付与することで、マウントしたディレクトリへの書き込みを禁止できる。


セキュリティ上の注意事項

下表に、Filesystem MCP Serverを安全に使用するための推奨事項を示す。

セキュリティに関する推奨事項
項目 説明
許可ディレクトリの最小化 必要最小限のディレクトリのみを許可対象として指定する。
ルートディレクトリ (/ や C:\) を許可対象に含めることは避けること。
読み取り専用の活用 書き込みが不要な用途では、
Dockerの :ro フラグを使用して読み取り専用で実行することを推奨する。
バージョン管理 過去バージョンにパス検証の脆弱性が存在したため、常に最新バージョンを使用すること。
最新版では修正済みである。



使用例

Filesystem MCP Serverのツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。

ファイルの読み取り

ファイルの内容を読み込む場合の操作例を以下に示す。

  • 単一ファイルを読み込む場合 
     # プロンプト例 :
 
 /home/user/Projects/config.yaml の内容を読み込んでください。

  • 複数ファイルをまとめて読み込む場合 
     # プロンプト例 :
 
 src/main.py と src/utils.py の2つのファイルを同時に読み込んでください。


ディレクトリの参照

ディレクトリの内容を確認する場合の操作例を以下に示す。

  • ディレクトリの一覧を表示する場合 
     # プロンプト例 :
 
 /home/user/Projects ディレクトリの内容を一覧表示してください。

  • ディレクトリ構造をツリー形式で確認する場合 
     # プロンプト例 :
 
 /home/user/Projects/myapp のディレクトリツリーを表示してください。


ファイルの作成・編集

ファイルを作成または編集する場合の操作例を以下に示す。

  • 新しいファイルを作成する場合 
     # プロンプト例 :
 
 /home/user/Projects/myapp/README.md を作成して、プロジェクトの概要を記述してください。

  • 既存ファイルを編集する場合 
     # プロンプト例 :
 
 /home/user/Projects/myapp/config.py の DEBUG 変数の値を False に変更してください。


ファイルの検索

特定のファイルを検索する場合の操作例を以下に示す。

  • globパターンでPythonファイルを検索する場合 
     # プロンプト例 :
 
 /home/user/Projects 配下にある全ての .py ファイルを検索してください。



トラブルシューティング

共通の問題

下表に、OS問わず発生する可能性がある問題と対処法を示す。

共通トラブルシューティング
問題 原因 対処法
Server transport closed unexpectedly エラーが発生する PATHの問題
NVM等のバージョンマネージャを使用している場合に発生しやすい。		 Node.jsの完全パスを設定ファイルの command に指定する。
または、NVM向けのラッパースクリプトを作成して使用する。
MCP filesystem: Server disconnected エラーが発生する NVM環境での実行時に環境が正しく初期化されていない。 シェルの設定ファイルでNVMを正しく初期化した上でMCPクライアントを起動する。
または、nvm use を実行してからMCPクライアントを起動する。
設定ファイルが読み込まれない JSONファイルにコメントが含まれている。
JSON標準仕様ではコメントは使用不可である。		 設定ファイルからコメントを全て削除する。
アクセスが拒否される 指定した許可ディレクトリの外にあるファイルへのアクセスを試みている。 list_allowed_directories ツールで許可ディレクトリを確認し、
必要に応じてサーバの起動引数に対象ディレクトリを追加する。


Windowsでの問題

下表に、Windows環境で発生する可能性がある問題と対処法を示す。

Windowsのトラブルシューティング
問題 原因 対処法
パスが正しく認識されない OneDriveが有効な場合、表示上のパスと実際のパスが異なることがある。 エクスプローラーでフォルダのプロパティを確認し、
実際のパスを設定ファイルに記述する。
サーバが起動しない npx コマンドがWindowsのパス解決で問題を起こすことがある。 command に cmd、args の先頭に
["/c", "npx"] を追加して cmd /c ラッパーを使用する。


一般的なデバッグ手順

問題が発生した場合は、以下に示す手順でデバッグを行う。

  1. MCPクライアント (Claude Desktop等) を完全に終了する。
  2. 設定ファイルのJSON構文を検証する。(JSONリンターを使用する)
  3. Node.jsのバージョンが、v18.0.0以上であることを確認する。
  4. npx コマンドが使用可能であることを確認する。(npx --version を実行する)
  5. 以下に示すコマンドを手動で実行してサーバが正常に起動するか確認する。
    npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory
  6. MCPクライアントを再起動する。



「https://mochiu.net/index.php?title=MCPサーバ_-_Filesystem&oldid=14615」から取得