MCPサーバ - Filesystemのソースを表示

== 概要 ==
Filesystem MCP Server (@modelcontextprotocol/server-filesystem) は、AnthropicがNode.jsで実装したMCPサーバである。<br>
MITライセンスで公開されている。<br>
<br>
Model Context Protocol (MCP) を通じて、AIアシスタントにローカルファイルシステムへの安全で制御されたアクセスを提供する。<br>
起動時に許可するディレクトリを明示的に指定することで、AIアシスタントはそのディレクトリ内に限定したファイル操作を実行できる。<br>
<br>
Claude Desktop、Claude Code、VS Code、Cursor等の主要なMCPクライアントに対応している。<br>
Windows、MacOS、Linuxに対応する。<br>
<br>
主な特徴は以下の通りである。<br>
* 14個のファイル操作ツールを提供 (読み取り、書き込み、ディレクトリ管理、検索等)
* 指定ディレクトリ外へのアクセスをブロックするパストラバーサル防止機能
* Dockerイメージ (mcp/filesystem) による実行にも対応
* Rootsプロトコルによる実行時のディレクトリ動的更新
* Dockerの <code>:ro</code> フラグを使用した読み取り専用アクセスの設定が可能
<br><br>

== 動作要件 ==
==== 前提条件 ====
Filesystem MCP Serverを使用するために必要な前提条件を以下に示す。<br>
<br>
* Node.js v18.0.0以上
*: <code>npx</code> コマンドを使用してFilesystem MCP Serverを実行するために必要
* <code>npx</code> コマンド
*: Node.jsに同梱されているため、Node.jsのインストールで利用可能になる。
* Docker (オプション)
*: Dockerを使用してFilesystem MCP Serverを実行する場合に必要
<br><br>

== インストール ==
==== npxを使用した実行 ====
<code>npx</code> コマンドを使用する場合、インストール不要でFilesystem MCP Serverを直接実行できる。<br>
アクセスを許可するディレクトリへの絶対パスをコマンドライン引数で指定する (複数指定可能)。<br>
<br>
 npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory1 /path/to/allowed/directory2
<br>
MCPクライアントの設定ファイルで指定する場合は、後述の各クライアント設定を参照すること。<br>
<br>
==== Dockerを使用した実行 ====
Docker Hubに公式イメージ (mcp/filesystem) が公開されており、Node.jsをインストールせずにFilesystem MCP Serverを実行できる。<br>
<br>
以下に示すコマンドを実行することにより、ローカルディレクトリをコンテナ内の <code>/projects</code> にマウントしてサーバを起動する。<br>
<code>:ro</code> フラグを付与することで、読み取り専用アクセスとなる。<br>
<br>
 docker run -i --rm -v /path/to/local/directory:/projects:ro mcp/filesystem
<br>
書き込みアクセスを許可する場合は、<code>:ro</code> フラグを省略する。<br>
<br>
 docker run -i --rm -v /path/to/local/directory:/projects mcp/filesystem
<br><br>

== MCPクライアントの設定 ==
==== 設定ファイルの場所 ====
各MCPクライアントの設定ファイルの場所は以下の通りである。<br>
<br>
Claude Desktopの設定ファイルを以下に示す。<br>
* Linux
*: <u>~/.config/Claude/claude_desktop_config.json</u>
* MacOS
*: <u>~/Library/Application Support/Claude/claude_desktop_config.json</u>
* Windows
*: <u>%APPDATA%\Claude\claude_desktop_config.json</u>
<br>
Claude Codeの設定ファイルを以下に示す。<br>
* ローカルスコープ
*: <u>.mcp.json</u> (プロジェクトルート) : <code>claude mcp add</code> コマンドで生成される。
* ユーザスコープ
*: <u>~/.claude.json</u> (ホームディレクトリ)
<br>
VS Codeの設定ファイルを以下に示す。<br>
* <u>.vscode/mcp.json</u> (プロジェクトルート)
<br>
Cursorの設定ファイルを以下に示す。<br>
* グローバル設定
*: <u>~/.cursor/mcp.json</u>
* プロジェクト設定
*: <u>.cursor/mcp.json</u>
<br>
==== Claude Desktopの設定 ====
<u>claude_desktop_config.json</u> ファイルに以下に示す内容を設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory1", "/path/to/allowed/directory2"]
     }
   }
 }
 </syntaxhighlight>
<br>
設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。<br>
<br>
==== Claude Codeの設定 ====
Claude Codeでは、<code>claude mcp add</code> コマンドを使用してFilesystem MCP Serverを追加できる。<br>
<br>
以下に示すコマンドで、MCPサーバをClaude Codeに登録する。<br>
<br>
 claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory
<br>
プロジェクトスコープで設定する場合は、<code>--scope project</code> オプションを追加する。<br>
設定は、<u>.mcp.json</u> ファイルに保存される。<br>
<br>
 claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory
<br>
上記コマンドにより生成される <u>.mcp.json</u> ファイルの内容を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
     }
   }
 }
 </syntaxhighlight>
<br>
==== OpenCodeの設定 ====
OpenCodeでは、プロジェクトルートまたはグローバル設定の <u>opencode.json</u> ファイルにMCPサーバを定義する。<br>
<br>
設定ファイルの読み込み優先順位は以下の通りである。(後の設定が前の設定にマージされる)<br>
* グローバル設定
*: <u>~/.config/opencode/opencode.json</u>
* プロジェクト設定
*: プロジェクトルートの <u>opencode.json</u>
<br>
<u>opencode.json</u> ファイルに以下の内容を記述して、Filesystem MCP Serverを登録する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "filesystem": {
       "type": "local",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
       "enabled": true
     }
   }
 }
</syntaxhighlight>
<br>
複数のディレクトリへのアクセスを許可する場合は、<code>command</code> 配列にディレクトリパスを追加する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "filesystem": {
       "type": "local",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir1", "/path/to/dir2"],
       "enabled": true
     }
   }
 }
 </syntaxhighlight>
<br>
MCPサーバを一時的に無効にする場合は、<code>enabled</code> を <code>false</code> に設定する。<br>
<br>

==== VS Codeの設定 ====
<u>.vscode/mcp.json</u> ファイルに以下に示す内容を設定する。<br>
変数 <code>${workspaceFolder}</code> を使用することにより、ワークスペースのルートディレクトリを自動的に許可対象に指定できる。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
     }
   }
 }
 </syntaxhighlight>
<br>
==== Cursorの設定 ====
<u>~/.cursor/mcp.json</u> (グローバル設定) または <u>.cursor/mcp.json</u> (プロジェクト設定) ファイルに以下に示す内容を設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
     }
   }
 }
 </syntaxhighlight>
<br>
==== プロジェクトルートのみ参照する場合 ====
.mcp.json / opencode.jsonファイルがあるディレクトリ自体を指すには、相対パス <code>.</code> を指定する。<br>
<code>.</code> は、MCPサーバ起動時のカレントディレクトリ (一般的には、.mcp.json / opencode.jsonファイルがあるプロジェクトルート) を指す。<br>
<br>
サブディレクトリに限定する場合は、<u>./src</u> のように指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
     }
   }
 }
 </syntaxhighlight>
<br><br>

== 提供ツール ==
Filesystem MCP Serverは、ファイル読み取り、ファイル書き込み、ディレクトリ管理、ファイル検索・管理の4カテゴリで合計14個のツールを提供する。<br>
<br>
==== ファイル読み取りツール ====
下表に、ファイルの内容を読み込むためのツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ ファイル読み取りツールの一覧
! ツール名 !! 説明
|-
| <code>read_file</code> || 指定したファイルの完全な内容を読み込む。
|-
| <code>read_text_file</code> || テキストファイルを読み込む。<br><code>read_file</code> よりも詳細なエラーメッセージを提供する。
|-
| <code>read_media_file</code> || 画像やオーディオファイルをBase64エンコードして読み込む。
|-
| <code>read_multiple_files</code> || 複数のファイルを同時に読み込む。
|}
</center>
<br>
==== ファイル書き込みツール ====
下表に、ファイルの作成・編集を行うためのツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ ファイル書き込みツールの一覧
! ツール名 !! 説明
|-
| <code>write_file</code> || ファイルを新規作成する。<br>既存ファイルが存在する場合は上書きする。
|-
| <code>edit_file</code> || 行ベースの編集を行う。<br>検索・置換操作に対応し、git形式のdiffを出力する。
|}
</center>
<br>
==== ディレクトリ管理ツール ====
下表に、ディレクトリの作成・参照を行うためのツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ ディレクトリ管理ツールの一覧
! ツール名 !! 説明
|-
| <code>create_directory</code> || ディレクトリを作成する。<br>ネストしたディレクトリ構造の作成にも対応する。
|-
| <code>list_directory</code> || ディレクトリの内容を一覧表示する。<br>ファイルには <code>[FILE]</code>、ディレクトリには <code>[DIR]</code> のプレフィックスが付与される。
|-
| <code>list_directory_with_sizes</code> || ファイルサイズを含むディレクトリの内容を一覧表示する。
|-
| <code>directory_tree</code> || ディレクトリ構造をJSON形式のツリーとして取得する。
|}
</center>
<br>
==== ファイル検索・管理ツール ====
下表に、ファイルの検索・メタデータ取得・移動に関するツールを示す。<br>
<br>
<center>
{| class="wikitable"
|+ ファイル検索・管理ツールの一覧
! ツール名 !! 説明
|-
| <code>search_files</code> || グロブパターンを使用してファイルを再帰的に検索する。
|-
| <code>get_file_info</code> || ファイルのメタデータを取得する。<br>取得できる情報: ファイルサイズ、作成日時、更新日時等
|-
| <code>move_file</code> || ファイルまたはディレクトリを移動する。<br>ファイル、ディレクトリのリネームにも使用できる。
|-
| <code>list_allowed_directories</code> || サーバ起動時に許可として設定されたディレクトリの一覧を表示する。
|}
</center>
<br><br>

== セキュリティ ==
==== アクセス制限の仕組み ====
Filesystem MCP Serverは、起動時に指定したディレクトリのみへのアクセスを許可する設計となっている。<br>
指定ディレクトリ外へのアクセス試行はブロックされる。<br>
<br>
主なセキュリティ機能を以下に示す。<br>
* 指定ディレクトリへのアクセス制限
*: サーバ起動時にコマンドライン引数で指定したディレクトリのみにアクセスを限定する。
* パストラバーサル防止
*: <code>../</code> 等を利用した許可ディレクトリ外へのアクセスを防止する。
* Rootsプロトコルによる動的更新
*: MCPのRootsプロトコルにより、実行時に許可ディレクトリを動的に更新できる。
* Docker使用時の読み取り専用設定
*: Docker実行時に <code>:ro</code> フラグを付与することで、マウントしたディレクトリへの書き込みを禁止できる。
<br>
==== セキュリティ上の注意事項 ====
下表に、Filesystem MCP Serverを安全に使用するための推奨事項を示す。<br>
<br>
<center>
{| class="wikitable"
|+ セキュリティに関する推奨事項
! 項目 !! 説明
|-
| 許可ディレクトリの最小化 || 必要最小限のディレクトリのみを許可対象として指定する。<br>ルートディレクトリ (/ や C:\) を許可対象に含めることは避けること。
|-
| 読み取り専用の活用 || 書き込みが不要な用途では、<br>Dockerの <code>:ro</code> フラグを使用して読み取り専用で実行することを推奨する。
|-
| バージョン管理 || 過去バージョンにパス検証の脆弱性が存在したため、常に最新バージョンを使用すること。<br>最新版では修正済みである。
|}
</center>
<br><br>

== 使用例 ==
Filesystem MCP Serverのツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。<br>
<br>
==== ファイルの読み取り ====
ファイルの内容を読み込む場合の操作例を以下に示す。<br>
<br>
* 単一ファイルを読み込む場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects/config.yaml の内容を読み込んでください。
 </syntaxhighlight>
*: <br>
* 複数ファイルをまとめて読み込む場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 src/main.py と src/utils.py の2つのファイルを同時に読み込んでください。
 </syntaxhighlight>
*: <br>
<br>
==== ディレクトリの参照 ====
ディレクトリの内容を確認する場合の操作例を以下に示す。<br>
<br>
* ディレクトリの一覧を表示する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects ディレクトリの内容を一覧表示してください。
 </syntaxhighlight>
*: <br>
* ディレクトリ構造をツリー形式で確認する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects/myapp のディレクトリツリーを表示してください。
 </syntaxhighlight>
*: <br>
<br>
==== ファイルの作成・編集 ====
ファイルを作成または編集する場合の操作例を以下に示す。<br>
<br>
* 新しいファイルを作成する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects/myapp/README.md を作成して、プロジェクトの概要を記述してください。
 </syntaxhighlight>
*: <br>
* 既存ファイルを編集する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects/myapp/config.py の DEBUG 変数の値を False に変更してください。
 </syntaxhighlight>
*: <br>
<br>
==== ファイルの検索 ====
特定のファイルを検索する場合の操作例を以下に示す。<br>
<br>
* globパターンでPythonファイルを検索する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 /home/user/Projects 配下にある全ての .py ファイルを検索してください。
 </syntaxhighlight>
*: <br>
<br><br>

== トラブルシューティング ==
==== 共通の問題 ====
下表に、OS問わず発生する可能性がある問題と対処法を示す。<br>
<br>
<center>
{| class="wikitable"
|+ 共通トラブルシューティング
! 問題 !! 原因 !! 対処法
|-
| <u>Server transport closed unexpectedly</u> エラーが発生する || PATHの問題<br>NVM等のバージョンマネージャを使用している場合に発生しやすい。 || Node.jsの完全パスを設定ファイルの <code>command</code> に指定する。<br>または、NVM向けのラッパースクリプトを作成して使用する。
|-
| <u>MCP filesystem: Server disconnected</u> エラーが発生する || NVM環境での実行時に環境が正しく初期化されていない。 || シェルの設定ファイルでNVMを正しく初期化した上でMCPクライアントを起動する。<br>または、<code>nvm use</code> を実行してからMCPクライアントを起動する。
|-
| 設定ファイルが読み込まれない || JSONファイルにコメントが含まれている。<br>JSON標準仕様ではコメントは使用不可である。 || 設定ファイルからコメントを全て削除する。
|-
| アクセスが拒否される || 指定した許可ディレクトリの外にあるファイルへのアクセスを試みている。 || <code>list_allowed_directories</code> ツールで許可ディレクトリを確認し、<br>必要に応じてサーバの起動引数に対象ディレクトリを追加する。
|}
</center>
<br>
==== Windowsでの問題 ====
下表に、Windows環境で発生する可能性がある問題と対処法を示す。<br>
<br>
<center>
{| class="wikitable"
|+ Windowsのトラブルシューティング
! 問題 !! 原因 !! 対処法
|-
| パスが正しく認識されない || OneDriveが有効な場合、表示上のパスと実際のパスが異なることがある。 || エクスプローラーでフォルダのプロパティを確認し、<br>実際のパスを設定ファイルに記述する。
|-
| サーバが起動しない || <code>npx</code> コマンドがWindowsのパス解決で問題を起こすことがある。 || <code>command</code> に <code>cmd</code>、<code>args</code> の先頭に<br><code>["/c", "npx"]</code> を追加して <code>cmd /c</code> ラッパーを使用する。
|}
</center>
<br>
==== 一般的なデバッグ手順 ====
問題が発生した場合は、以下に示す手順でデバッグを行う。<br>
<br>
# MCPクライアント (Claude Desktop等) を完全に終了する。
# 設定ファイルのJSON構文を検証する。(JSONリンターを使用する)
# Node.jsのバージョンが、v18.0.0以上であることを確認する。
# <code>npx</code> コマンドが使用可能であることを確認する。(<code>npx --version</code> を実行する)
# 以下に示すコマンドを手動で実行してサーバが正常に起動するか確認する。
#: <code>npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory</code>
# MCPクライアントを再起動する。
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板,Filesystem,MCP,Model Context Protocol,filesystem-mcp-server,Claude,Claude Desktop,Claude Code,VS Code,Cursor,Node.js,npx,Docker,ファイルシステム,AIアシスタント,MCPサーバ
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]