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

ファイルシステム操作のための強力なモデルコンテキストプロトコル（MCP）サーバー。大容量ファイルやファイルシステムとのインテリジェントな連携に最適化されています。スマートなコンテキスト管理により、ファイルやディレクトリへの安全なアクセスを提供し、膨大なデータを扱う際の効率を最大限に高めます。

MCP ファイルシステムを選ぶ理由

スマートコンテキスト管理: 大きなファイルやファイルシステムを効率的に操作
- 関連するコンテンツのみに焦点を当てた部分的な読み取り
- 必要なものを正確に見つけるための正確なコンテキストコントロール
- ページネーションによるトークン効率の高い検索結果
- リクエストのオーバーヘッドを削減するための複数ファイル操作
インテリジェントなファイル操作:
- 設定可能なコンテキストウィンドウによる行単位の読み取り
- 競合を防ぐためのコンテンツ検証を備えた高度な編集
- 標準のgrepを超えるきめ細かな検索機能
- 正確なファイル操作のための相対行参照

主な特徴

セキュアファイルアクセス: 明示的に許可されたディレクトリ内でのみ操作を許可します
包括的な操作:ファイルシステム機能のフルセット
- 標準操作（読み取り、書き込み、一覧表示、移動、削除）
- 強化された操作 (ツリーの視覚化、重複の検出など)
- grep 統合による高度な検索 (利用可能な場合は ripgrep を使用)
  - コンテキスト制御（grepの-A/-B/-Cオプションのような）
  - 大規模な結果セットの結果ページ区切り
- コンテンツ検証と相対行番号による行対象操作
パフォーマンスの最適化:
- 大きなファイルやディレクトリを効率的に処理します
- Ripgrep 統合による超高速検索
- ファイル全体の読み込みを回避するための行単位の操作
包括的なテスト：行動駆動型アプローチによる75以上のテスト
クロスプラットフォーム: Windows、macOS、Linuxで動作

クイックスタートガイド

1. クローンとセットアップ

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

# Install uv using the official installer
curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

# Or with pipx
pipx install uv

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

# Clone the repository
git clone https://github.com/safurrier/mcp-filesystem.git
cd mcp-filesystem

# Install dependencies with uv
uv pip sync requirements.txt requirements-dev.txt

2. 絶対パスを取得する

リポジトリの場所とアクセスするディレクトリの両方に絶対パスが必要です。

# Get the absolute path to the repository
REPO_PATH=$(pwd)
echo "Repository path: $REPO_PATH"

# Get absolute paths to directories you want to access
realpath ~/Documents
realpath ~/Downloads
# Or on systems without realpath:
echo "$(cd ~/Documents && pwd)"

3. Claudeデスクトップを設定する

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を使用して、正しい絶対パスであるrealpathを確認してください。

4. Claude Desktopを再起動します

設定を保存した後、変更を有効にするために Claude Desktop を再起動します。

インストール

使用法

サーバーログを監視する

Claude Desktop からサーバーログを監視するには、次の操作を行います。

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

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

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

サーバーの実行

特定のディレクトリへのアクセス権を持つサーバーを実行します。

# Using uv (recommended)
uv run run_server.py /path/to/dir1 /path/to/dir2

# Or using standard Python
python run_server.py /path/to/dir1 /path/to/dir2

# Example with actual paths
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 を使用した対話型テストとデバッグの場合:

# Basic usage
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory

# With SSE transport
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --transport sse --port 8080

# With debug output
npx @modelcontextprotocol/inspector uv run run_server.py /path/to/directory --debug

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

クロードデスクトップ統合

Claude Desktop 構成ファイルを編集して、MCP ファイルシステムを統合します。

設定ファイルの場所:

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

発達

テストの実行

# Run all tests
uv run -m pytest tests/

# Run specific test file
uv run -m pytest tests/test_operations_unit.py

# Run with coverage
uv run -m pytest tests/ --cov=mcp_filesystem --cov-report=term-missing

コードスタイルと品質

# Format code
uv run -m ruff format mcp_filesystem

# Lint code
uv run -m ruff check --fix mcp_filesystem

# Type check
uv run -m mypy mcp_filesystem

# Run all checks
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-based indexing (line 100)
  "limit": 51,         # Read 51 lines
  "encoding": "utf-8"  # Optional encoding
}

Grepでコンテンツを検索する

Tool: grep_files
Arguments: {
  "path": "/path/to/search",
  "pattern": "function\\s+\\w+\\(",
  "is_regex": true,
  "context_before": 2,       # Show 2 lines before each match (like grep -B)
  "context_after": 5,        # Show 5 lines after each match (like grep -A)
  "include_patterns": ["*.js", "*.ts"],
  "results_offset": 0,       # Start from the first match
  "results_limit": 20        # Show at most 20 matches
}

行ターゲット編集

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" # Verify content before editing
    },
    {
      "line_number": 20,
      "action": "delete"
    }
  ],
  "offset": 0,                           # Start considering lines from this offset
  "relative_line_numbers": false,        # Whether line numbers are relative to offset
  "abort_on_verification_failure": true, # Stop on verification failure
  "dry_run": true                        # Preview changes without applying
}

重複ファイルの検索

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

大規模ファイルとファイルシステムのための効率的なワークフロー

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

スマートコンテキスト検出
- grep_files使用すると、正確なコンテキスト制御で必要なものを正確に見つけることができます。
- 一致の前後のコンテキスト行を細かく制御することで、トークンの無駄を防止します。
- トークン制限に圧倒されることなく、大規模な結果セットを効率的にページ分割します
- Ripgrep統合により、数百万のファイルと行を含む大規模なファイルシステムを処理できます。
ターゲットリーディング
- offset/limitを使用してread_file_linesで関連セクションのみを調べる
- 正確なコンテンツ検索のためのシンプルなオフセット/制限パラメータによるゼロベースのインデックス
- トークンの効率を最大化するために読み取る行数を正確に制御します
- 複数のファイルを同時に読み取り、往復の回数を減らす
正確な編集
- コンテンツ検証付きのedit_file_at_lineで対象を絞った編集を行う
- 競合を防ぐために編集前にコンテンツが変更されていないことを確認する
- 複雑なファイル内の部分編集には相対行番号を使用する
- 複雑な変更を1回の操作で複数の編集アクションで実行
- 変更を適用する前にプレビューできるドライラン機能
高度な分析
- find_duplicate_filesやcompare_filesなどの専用ツールを使用する
- 素早いナビゲーションのために、 directory_treeを使用してディレクトリツリーを生成します。
- find_large_filesとfind_empty_directoriesを使用して問題のある領域を特定する

このワークフローは、大規模なファイルやファイルシステムを扱う必要があるAI搭載ツールにとって特に有益です。例えば、Claudeなどの高度なAIアシスタントは、これらの機能を活用して、コードベースを効率的にナビゲートしたり、ログファイルを分析したり、トークン効率を維持しながら大規模なテキストベースのデータセットを操作したりすることができます。

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

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

トークン効率
- スマートな行ターゲット操作により、ファイル全体をコンテキストに読み込むことを回避します。
- 大きな結果のページネーション制御により、コンテキストのオーバーフローを防止
- コンテキスト制御による正確な grep (ファイル全体の検索だけでなく)
- 複数ファイルの読み取りにより、往復リクエストが削減されます
インテリジェント編集
- 編集上の競合を防ぐためのコンテンツ検証
- ファイル全体を必要としない行単位の編集
- 相対行番号のサポートにより、地域編集が容易になりました
- 変更を適用する前にプレビューできるドライラン機能
詳細検索
- 大規模なファイルシステムパフォーマンスを実現する Ripgrep 統合
- コンテキストに応じた結果（一致だけでなく）
- 返されるものを細かく制御
- 除外サポート付きのパターンベースのファイル検索
追加ユーティリティ
- ファイルの比較と重複排除
- ディレクトリサイズの計算と分析
- 空のディレクトリ識別
- ツリーベースのディレクトリ視覚化
セキュリティフォーカス
- 堅牢なパス検証とサンドボックス
- パストラバーサル攻撃に対する保護
- シンボリックリンクの検証とセキュリティ
- 機密情報を公開せずに詳細なエラーレポートを作成

既知の問題と制限事項

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

安全

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

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

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

grep 機能で最高のパフォーマンスを得るには:

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

ライセンス

MITライセンス

MCP Filesystem Server

Integrations