File System MCP Server

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

FastMCP で構築された強力なファイルシステム管理サーバーです。ファイルやディレクトリを操作するための包括的なツールセットを提供します。構造化された API を介してさまざまなファイルシステム操作を実行できるため、自動化や他のシステムとの統合に最適です。

プラットフォームのサポート

このサーバーはさまざまなオペレーティングシステムで動作するよう設計されていますが、機能の対応状況は異なります。

Windows

• すべての機能をサポート
• ドライブの一覧表示
• 特殊フォルダーへのアクセス
• Windows 固有のパス処理
• 詳細なシステム情報

macOS/Linux

• 基本的なファイル操作
• ディレクトリ操作
• ファイル検索とメタデータ
• 基本的なシステム情報
• 注：Windows 固有の機能の一部は利用できません

今後の実装

macOS のサポート予定

• macOS 用のネイティブなパス処理
• macOS 固有のシステム情報の取得
• macOS のファイルシステム機能との統合
• macOS 固有のファイル属性のサポート
• macOS 固有のユーティリティの実装（windows_utils.py に類似）

Linux のサポート予定

• Linux 用のネイティブなパス処理
• Linux 固有のシステム情報の取得
• Linux のファイルシステム機能との統合
• Linux のファイル権限と属性のサポート
• Linux 固有のユーティリティの実装

クロスプラットフォームの改善

• 統一されたパス処理システム
• プラットフォームに依存しないドライブ検出
• 一貫性のあるシステム情報 API
• プラットフォーム間で標準化されたファイル属性
• クロスプラットフォームのファイルシステムイベント監視
• 汎用的なファイル収集システム

スケジュール

• フェーズ 1：基本的なクロスプラットフォーム互換性の改善
• フェーズ 2：プラットフォーム固有の機能の実装
• フェーズ 3：高度なクロスプラットフォーム機能
• フェーズ 4：パフォーマンスの最適化と改良

機能

ファイル操作

• バックアップに対応したファイルのコピー
• バックアップに対応したファイルの移動
• 安全性チェック付きのファイル削除
• ファイル内容の読み取り
• ファイル内容の書き込み
• ファイル情報の取得（サイズ、作成日時、更新日時）
• 名前のパターンによるファイル検索
• 関連ファイルを整理するためのファイルコレクションの作成

ディレクトリ操作

• ディレクトリ内容の一覧表示
• ディレクトリの作成
• ディレクトリの削除
• ディレクトリの再帰的な一覧表示（ツリー形式）
• 名前のパターンによるディレクトリ検索

システム情報

• システム情報の取得（OS、CPU、メモリ、ディスク使用量）
• ディスク情報の取得（合計容量、使用容量、空き容量）
• ディレクトリ情報の取得（ファイル数、合計サイズ）

プロジェクト構成

file-system-mcp-server/
├── fs_server.py            # Main server implementation
├── windows_utils.py        # Windows-specific utilities (Windows only)
├── requirements.txt        # Project dependencies
└── test_prompts_example.md # Example test prompts

コレクションの保存先

コレクションは、ユーザーが指定した任意のディレクトリに保存できます。保存先が指定されていない場合は、プロジェクトの data/collections ディレクトリ内にあるデフォルトの場所に保存されます。

使用例：

# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])

# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

依存関係

必須の依存関係

• FastMCP
• Pydantic
• pywin32（Windows のみ）
• WMI（Windows のみ）

依存関係をインストールするには：

pip install -r requirements.txt

セットアップ

1. リポジトリをクローンします：

git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server

2. 仮想環境を作成して有効化します：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 依存関係をインストールします：

pip install -r requirements.txt

使用方法

Claude、Cursor、Windsurf など、さまざまな開発環境での MCP 設定手順については、次のページをご覧ください： MCP 設定ガイド

Claude との統合

ファイルシステム MCP サーバーを Claude と統合するには、次の内容を claude_desktop_config.json ファイルに追加します。

{
  "mcpServers": {
    "file-system": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Python のパスの確認

Python 実行ファイルのパスを確認するには、次のコマンドを使用します。

Windows（PowerShell）：

(Get-Command python).Source

Windows（コマンドプロンプト/ターミナル）：

where python

Linux/macOS（ターミナル）：

which python

/absolute/path/to/python を、上記の該当するコマンドの出力に置き換えます。

設定例

Windows の場合、設定は次のようになります。

{
  "mcpServers": {
    "file-system": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
      "args": [
        "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

macOS/Linux の場合：

{
  "mcpServers": {
    "file-system": {
      "command": "/usr/local/bin/python3",
      "args": [
        "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

設定を追加した後：

1. claude_desktop_config.json ファイルを保存します
2. Claude を再起動します
3. Claude にファイル操作を依頼すると、ファイルシステムツールを使用できます

利用可能なツール

ファイル操作

• copy_file：任意でバックアップを作成してファイルをコピーします
• move_file：任意でバックアップを作成してファイルを移動します
• delete_file：安全性を確認してファイルを削除します
• read_file：ファイルの内容を読み取ります
• write_file：ファイルに内容を書き込みます
• get_file_info：ファイルの詳細情報を取得します
• search_files：名前のパターンでファイルを検索します
• create_collection：ファイルのコレクションを作成します

ディレクトリ操作

• list_directory：ディレクトリの内容を一覧表示します
• create_directory：新しいディレクトリを作成します
• delete_directory：ディレクトリを削除します
• list_directory_recursively：ディレクトリ構造をツリー形式で表示します
• search_directories：名前のパターンでディレクトリを検索します

システム情報

• get_system_info：システム情報を取得します
• get_disk_info：ディスク使用状況の情報を取得します
• get_directory_info：ディレクトリの統計情報を取得します

既知の問題

以下の機能では現在問題が発生しており、期待どおりに動作しない場合があります。

1. ファイル削除機能

   • delete_file 関数は、場合によってファイルを正しく削除できないことがあります
   • ファイルの削除を手動で確認するか、重要な場合は別の方法を使用することをおすすめします
   • この問題は調査中で、今後のアップデートで修正される予定です

2. ドライブ一覧表示機能

   • list_drives 関数は、利用可能なすべてのドライブを正しく検出または表示できない場合があります
   • 一部のドライブが一覧から欠落したり、誤った情報が表示されたりすることがあります
   • これは既知の制限であり、今後のアップデートで対応予定です

3. プラットフォーム固有の制限

   • Windows 固有の機能は macOS/Linux では利用できません
   • パスの処理方法はプラットフォームによって異なる場合があります
   • システム情報の取得方法はプラットフォームによって異なります

エラー処理

サーバーには、以下を対象とする包括的なエラー処理が含まれています。

• 無効なファイルパス
• ファイル／ディレクトリが見つからない場合
• 権限の問題
• ディスク容量の制限
• 無効な操作
• プラットフォーム固有のエラー

セキュリティ

• すべてのファイル操作でパスの検証を行います
• 破壊的な操作の前にバックアップファイルを作成します
• システム情報へのアクセスは安全な操作に制限されています
• ファイル操作は適切なエラー処理を伴って実行されます

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• FastMCP を使用して構築されています
• データ検証に Pydantic を使用しています
• 最新のファイルシステム管理ツールに着想を得ています