MCP Filesystem

🚀 MCP Filesystem Server

強力なファイルシステム操作向けのModel Context Protocol (MCP)サーバーで、大きなファイルやファイルシステムとのインテリジェントなやり取りを最適化しています。スマートなコンテキスト管理により、ファイルやディレクトリへの安全なアクセスを提供し、大量のデータを扱う際の効率を最大化します。

🚀 クイックスタート

1. リポジトリのクローンとセットアップ

まだuvをインストールしていない場合は、まずインストールします。

# 公式インストーラーを使用してuvをインストール
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# またはpipxを使用する場合
pipx install uv

次に、リポジトリをクローンし、依存関係をインストールします。

# リポジトリをクローン
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# uvを使用して依存関係をインストール
uv pip sync requirements.txt requirements-dev.txt

2. 絶対パスの取得

リポジトリの場所とアクセスしたいディレクトリの絶対パスが必要です。

# リポジトリの絶対パスを取得
REPO_PATH=$(pwd)
echo "リポジトリのパス: $REPO_PATH"

# アクセスしたいディレクトリの絶対パスを取得
realpath ~/Documents
realpath ~/Downloads
# realpathがないシステムの場合
echo "$(cd ~/Documents && pwd)"

3. Claude Desktopの設定

Claude Desktopの設定ファイルを開きます。

• macOSの場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windowsの場合: %APPDATA%/Claude/claude_desktop_config.json

以下の設定を追加します（実際のパスを置き換えてください）。

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/absolute/path/to/dir1",
        "/absolute/path/to/dir2"
      ]
    }
  }
}

⚠️ 重要提示

すべてのパスは絶対パス（ルートディレクトリからの完全なパス）である必要があります。realpathまたはpwdを使用して、正しい絶対パスを取得してください。

4. Claude Desktopの再起動

設定を保存した後、Claude Desktopを再起動して変更を反映させます。

✨ 主な機能

なぜMCP-Filesystemを選ぶのか？

• スマートなコンテキスト管理: 大きなファイルやファイルシステムを効率的に操作できます。
  • 関連する内容のみに焦点を当てた部分読み取り
  • 必要なものを正確に見つけるための精密なコンテキスト制御
  • ページネーションによるトークン効率の高い検索結果
  • リクエストのオーバーヘッドを削減するマルチファイル操作
• インテリジェントなファイル操作:
  • 構成可能なコンテキストウィンドウを持つ行ターゲットの読み取り
  • 競合を防ぐための内容検証付きの高度な編集
  • 標準のgrepを超える細粒度の検索機能
  • 正確なファイル操作のための相対行参照

主要な機能

• セキュアなファイルアクセス: 明示的に許可されたディレクトリ内の操作のみを許可します。
• 包括的な操作: 完全なファイルシステム機能セット
  • 標準操作（読み取り、書き込み、リスト表示、移動、削除）
  • 拡張操作（ツリービジュアライズ、重複ファイル検索など）
  • grep統合による高度な検索（利用可能な場合はripgrepを使用）
    • コンテキスト制御（grepの -A/-B/-Cオプションのようなもの）
    • 大規模な結果セットのページネーション
  • 内容検証と相対行番号を持つ行ターゲットの操作
• パフォーマンス最適化:
  • 大きなファイルやディレクトリを効率的に処理
  • 高速な検索のためのripgrep統合
  • ファイル全体を読み込まない行ターゲットの操作
• 包括的なテスト: 振る舞い駆動アプローチによる75以上のテスト
• クロスプラットフォーム: Windows、macOS、Linuxで動作

📦 インストール

上述のクイックスタートガイドを参照してください。

💻 使用例

サーバーログの監視

Claude Desktopからサーバーログを監視することができます。

# macOSの場合
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

# Windows (PowerShell)の場合
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait

これは、問題のデバッグや、Claudeが正確に何を要求しているかを確認するのに特に役立ちます。

サーバーの実行

特定のディレクトリにアクセスしてサーバーを実行します。

# uvを使用する場合（推奨）
uv run run_server.py /path/to/dir1 /path/to/dir2

# 標準のPythonを使用する場合
python run_server.py /path/to/dir1 /path/to/dir2

# 実際のパスを使用した例
uv run run_server.py /Users/username/Documents /Users/username/Downloads

オプション

• --transport または -t: トランスポートプロトコル（stdioまたはsse、デフォルト: stdio）
• --port または -p: SSEトランスポートのポート（デフォルト: 8000）
• --debug または -d: デバッグログを有効にする
• --version または -v: バージョン情報を表示

MCP Inspectorとの使用

MCP Inspectorを使用して対話的なテストやデバッグを行うことができます。

# 基本的な使用法
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# SSEトランスポートを使用する場合
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# デバッグ出力を有効にする場合
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

このサーバーは、現在のMCPのベストプラクティスに合わせてFastMCP SDKを使用して構築されています。効率的なコンポーネントキャッシュシステムと直接デコレータパターンを使用しています。

📚 ドキュメント

Claude Desktopとの統合

Claude Desktopの設定ファイルを編集して、MCP-Filesystemを統合します。 設定ファイルの場所:

• macOSの場合: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windowsの場合: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem/repo",
        "run",
        "run_server.py"
      ]
    }
  }
}

特定のディレクトリへのアクセスを許可するには、追加の引数としてそれらを追加します。

{
  "mcpServers": {
    "mcp-filesystem": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem/repo",
        "run",
        "run_server.py",
        "/Users/yourusername/Projects",
        "/Users/yourusername/Documents"
      ]
    }
  }
}

⚠️ 重要提示

--directoryフラグは重要です。これは、uvにrun_server.pyを含むリポジトリの場所を伝えるためのものです。/path/to/mcp-filesystem/repoを、システム上でリポジトリをクローンした実際のパスに置き換えてください。

開発

テストの実行

# すべてのテストを実行
uv run -m pytest tests/

# 特定のテストファイルを実行
uv run -m pytest tests/test_operations_unit.py

# カバレッジを伴うテストを実行
uv run -m pytest tests/ --cov=mcp_filesystem --cov-report=term-missing

コードスタイルと品質

# コードをフォーマット
uv run -m ruff format mcp_filesystem

# コードをリント
uv run -m ruff check --fix mcp_filesystem

# 型チェック
uv run -m mypy mcp_filesystem

# すべてのチェックを実行
uv run -m ruff format mcp_filesystem && \
uv run -m ruff check --fix mcp_filesystem && \
uv run -m mypy mcp_filesystem && \
uv run -m pytest tests --cov=mcp_filesystem

利用可能なツール

基本的なファイル操作

• read_file: ファイルの完全な内容を読み取ります。
• read_multiple_files: 複数のファイルを同時に読み取ります。
• write_file: 新しいファイルを作成するか、既存のファイルを上書きします。
• create_directory: 新しいディレクトリを作成するか、ディレクトリが存在することを確認します。
• list_directory: ファイルやディレクトリの詳細なリストを取得します。
• move_file: ファイルやディレクトリを移動またはリネームします。
• get_file_info: ファイルまたはディレクトリの詳細なメタデータを取得します。
• list_allowed_directories: サーバーがアクセスを許可されているディレクトリをリストします。

行ターゲットの操作

• read_file_lines: オフセット/制限パラメータを使用して特定の行範囲を読み取ります。
• edit_file_at_line: 内容検証と相対行番号を使用して正確な編集を行います。
  • 古い内容の編集を防ぐための内容検証のサポート
  • より簡単な領域編集のための相対行番号
  • 複数の編集アクション（置換、挿入前、挿入後、削除）
• head_file: テキストファイルの最初のN行を読み取ります。
• tail_file: テキストファイルの最後のN行を読み取ります。

高度な検索

• grep_files: 強力なオプションを使用してファイル内のパターンを検索します。
  • パフォーマンスのためのripgrep統合（Pythonフォールバックあり）
  • 細粒度のコンテキスト制御（grepの -A/-B/-Cオプションのようなもの）
  • 大規模な検索結果のページネーション
  • 大文字小文字の区別と単語全体のオプションを持つ正規表現サポート
• search_files: 内容検索を伴うパターンに一致するファイルを検索します。
• directory_tree: ファイルやディレクトリの再帰的なツリービューを取得します。

分析とレポート

• calculate_directory_size: ディレクトリの合計サイズを計算します。
• find_duplicate_files: 内容を比較して重複ファイルを検索します。
• compare_files: 2つのテキストファイルを比較し、差分を表示します。
• find_large_files: 指定されたサイズより大きいファイルを検索します。
• find_empty_directories: 空のディレクトリを検索します。

具体的な使用例

ファイルの行を読み取る

Tool: read_file_lines
Arguments: {
  "path": "/path/to/file.txt",
  "offset": 99,        # 0から始まるインデックス（100行目）
  "limit": 51,         # 51行を読み取る
  "encoding": "utf-8"  # オプションのエンコーディング
}

grepを使用して内容を検索する

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # 各マッチの前に2行を表示（grepの -Bのようなもの）
  "context_after": 5,        # 各マッチの後に5行を表示（grepの -Aのようなもの）
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # 最初のマッチから開始
  "results_limit": 20        # 最大20件のマッチを表示
}

行ターゲットの編集

Tool: edit_file_at_line
Arguments: {
  "path": "/path/to/file.txt",
  "line_edits": [
    {
      "line_number": 15,
      "action": "replace",
      "content": "This is the new content for line 15\n",
      "expected_content": "Original content of line 15\n" # 編集前に内容を検証
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # このオフセットから行を考慮する
  "relative_line_numbers": false,        # 行番号がオフセットに対して相対的かどうか
  "abort_on_verification_failure": true, # 検証失敗時に中止する
  "dry_run": true                        # 変更を適用せずにプレビューする
}

重複ファイルを検索する

Tool: find_duplicate_files
Arguments: {
  "path": "/path/to/search",
  "recursive": true,
  "min_size": 1024,
  "format": "text"
}

大きなファイルやファイルシステムの効率的なワークフロー

MCP-Filesystemは、大きなファイルや複雑なファイルシステムとのインテリジェントなやり取りのために設計されています。

1. スマートなコンテキスト探索
   • grep_filesを使用して、精密なコンテキスト制御で必要なものを正確に見つけます。
   • マッチの前後のコンテキスト行の細粒度の制御により、トークンの無駄を防ぎます。
   • 大規模な結果セットを効率的にページングし、トークン制限を超えることを防ぎます。
   • ripgrep統合により、数百万のファイルと行を持つ巨大なファイルシステムを処理します。
2. ターゲット読み取り
   • read_file_linesを使用して、オフセット/制限を使用して関連するセクションのみを調べます。
   • ゼロベースのインデックスとシンプルなオフセット/制限パラメータにより、正確な内容を取得します。
   • 読み取る行数を正確に制御して、トークン効率を最大化します。
   • 複数のファイルを同時に読み取って、往復リクエストを削減します。
3. 正確な編集
   • edit_file_at_lineを使用して、内容検証を伴うターゲット編集を行います。
   • 編集前に内容が変更されていないことを検証して、競合を防ぎます。
   • 複雑なファイルの領域編集のために相対行番号を使用します。
   • 複数の編集アクションを単一の操作で行って、複雑な変更を行います。
   • 変更を適用する前にプレビューするためのドライラン機能。
4. 高度な分析
   • find_duplicate_filesやcompare_filesなどの特殊なツールを使用します。
   • directory_treeを使用してディレクトリツリーを生成し、迅速なナビゲーションを行います。
   • find_large_filesやfind_empty_directoriesを使用して問題のある領域を特定します。

このワークフローは、大きなファイルやファイルシステムを扱う必要があるAIパワードのツールに特に有価です。たとえば、Claudeや他の高度なAIアシスタントは、これらの機能を利用して、コードベースを効率的にナビゲートし、ログファイルを分析し、または任意の大規模なテキストベースのデータセットを処理することができます。

標準のファイルシステムMCPサーバーに対する利点

基本的なファイルシステムMCPサーバーとは異なり、MCP-Filesystemは以下の利点を提供します。

1. トークン効率
   • スマートな行ターゲットの操作により、ファイル全体をコンテキストに読み込む必要がなくなります。
   • 大規模な結果のページネーション制御により、コンテキストオーバーフローを防ぎます。
   • コンテキスト制御付きの精密なgrep（ファイル全体の検索ではなく）
   • マルチファイル読み取りにより、往復リクエストが削減されます。
2. インテリジェントな編集
   • 編集競合を防ぐための内容検証
   • ファイル全体を必要としない行ターゲットの編集
   • より簡単な領域編集のための相対行番号のサポート
   • 変更を適用する前にプレビューするためのドライラン機能
3. 高度な検索
   • 巨大なファイルシステムのパフォーマンスのためのripgrep統合
   • コンテキストを考慮した結果（単なるマッチではなく）
   • 返される内容の細粒度の制御
   • 除外サポート付きのパターンベースのファイル検索
4. 追加のユーティリティ
   • ファイルの比較と重複排除
   • ディレクトリサイズの計算と分析
   • 空のディレクトリの識別
   • ツリーベースのディレクトリビジュアライズ
5. セキュリティ重視
   • 堅牢なパス検証とサンドボックス化
   • パストラバーサル攻撃からの保護
   • シンボリックリンクの検証とセキュリティ
   • 機密情報を公開せずに詳細なエラーレポート

既知の問題と制限

• パス解決: 最も一貫した結果を得るには、常に絶対パスを使用してください。相対パスは、許可されたディレクトリではなく、サーバーの作業ディレクトリを基準に解釈される場合があります。
• パフォーマンス: 大きなディレクトリの場合、find_duplicate_filesや再帰的な検索などの操作には、完了までにかなりの時間がかかる場合があります。
• パーミッションの処理: サーバーは、実行しているユーザーと同じパーミッションで動作します。サーバーがアクセスする必要のあるディレクトリに適切なパーミッションがあることを確認してください。

セキュリティ

サーバーは、許可されたディレクトリ外へのアクセスを防ぐために、厳格なパス検証を実施します。

• 明示的に許可されたディレクトリ内の操作のみを許可します。
• パストラバーサル攻撃からの保護を提供します。
• シンボリックリンクが許可されたディレクトリ外を指さないことを検証します。
• 機密情報を公開せずに、意味のあるエラーメッセージを返します。

パフォーマンスに関する考慮事項

grep機能を最適なパフォーマンスで使用するには、以下のことを行ってください。

• ripgrep (rg)をインストールします。
• サーバーは、利用可能な場合は自動的にripgrepを使用し、Pythonフォールバックを行います。

📄 ライセンス

MIT License