Skip to main content
Glama
File Organizer MCP

File Organizer MCP

by kridaydave

File Organizer MCP サーバー

バージョン 3.5.0 | MCP プロトコル 2024-11-05 | Node.js 18+

npm version npm downloads License Tests

ファイルを整理する Model Context Protocol (MCP) サーバーです。Claude スタイルのアシスタントに対し、ファイルの分類・並べ替え・重複排除・名前変更を実行する単一のアトミック操作を提供します。多数のプリミティブな read・write・rename 呼び出しを連鎖させる必要はありません。


なぜ必要か

read・write・make・delete のみで構築されたファイルシステム MCP サーバーでは、アシスタントはすべての移動と名前変更を個別のステップとして計画する必要があります。各ステップはトークンを消費し、ステップが増えるほどパスを間違える可能性も高まります。

File Organizer MCP は、それらの連鎖を1回の呼び出しに置き換えます。

プリミティブなアプローチ

File Organizer MCP

多数の read / write / rename 呼び出し

organize_files() が移動全体をアトミックに実行

数十の推論ステップ

1つの推論ステップ

高いトークン使用量

最小限のトークン使用量

部分的な失敗で破損しやすい

ロールバック安全な操作


Related MCP server: MCP Filesystem Agent v3

クイックスタート

ワンコマンドセットアップ

npx file-organizer-mcp --setup

ウィザードがインストール済みの AI クライアント(Claude Desktop、Cursor、Windsurf、Cline など)を検出して設定し、フォルダ選択と環境設定を案内します。

要件

Node.js 18 以降。

セットアップ後

アシスタントに次のような依頼ができます。

  • 「ダウンロードフォルダを整理して」

  • 「ドキュメント内の重複ファイルを探して」

  • 「最も大きなファイルを表示して」

インストール方法

方法

コマンド

使用例

npx

npx file-organizer-mcp --setup

一時的な使用または試用

グローバル

npm install -g file-organizer-mcp

定期的な使用、起動が高速


機能

  • 12 種類以上のファイルタイプへの分類。

  • Cron ベースの自動整理とディレクトリ監視モード。

  • SHA-256 コンテンツハッシュによる重複検出。

  • メタデータ抽出:写真の EXIF、音声の ID3、ドキュメントのトピック抽出。

  • ファイルタイプごとに最適な戦略を選択するスマート整理。

  • ドライラン(プレビュー)、アトミックな移動、ロールバック。

  • パストラバーサル保護、TOCTOU 対策、メタデータスクラビング。

  • Windows、macOS、Linux に対応。


ツール

コアツール

  • file_organizer_scan_directory - 詳細なファイル情報を含むディレクトリを一覧表示します。directory は必須です。include_subdirs で再帰処理を切り替えます。

  • file_organizer_read_file - 8 層のパス検証付きでファイルを読み取ります。path は必須です。encoding は utf-8、base64、binary のいずれかです。

  • file_organizer_organize_smart - 音楽、写真、ドキュメントを1回のパスで処理し、ファイルごとに最適な戦略を選択します。

  • file_organizer_batch_rename - パターン、正規表現、または番号付けによって多数のファイル名を変更します。

  • file_organizer_undo_last_operation - 直近の整理操作を元に戻します。

全ツール一覧

  • file_organizer_analyze_duplicates

  • file_organizer_batch_read_files

  • file_organizer_categorize_by_type

  • file_organizer_delete_duplicates

  • file_organizer_find_duplicate_files

  • file_organizer_find_largest_files

  • file_organizer_get_categories

  • file_organizer_inspect_metadata

  • file_organizer_list_files

  • file_organizer_list_watches

  • file_organizer_organize_by_content

  • file_organizer_organize_files

  • file_organizer_organize_music

  • file_organizer_organize_photos

  • file_organizer_preview_organization

  • file_organizer_read_file

  • file_organizer_scan_directory

  • file_organizer_set_custom_rules

  • file_organizer_smart_suggest

  • file_organizer_system_organize

  • file_organizer_undo_last_operation

  • file_organizer_unwatch_directory

  • file_organizer_view_history

  • file_organizer_watch_directory

パラメータと戻り値の形式については、API.md を参照してください。


ファイルカテゴリ

カテゴリ

代表的な拡張子

実行ファイル

.exe、.msi、.bat、.sh

動画

.mp4、.avi、.mkv、.mov

ドキュメント

.pdf、.doc、.docx、.txt、.md

画像

.jpg、.jpeg、.png、.gif、.webp

音声

.mp3、.wav、.flac、.m4a

アーカイブ

.zip、.rar、.7z、.tar.gz

コード

.py、.js、.ts、.java、.go、.json


ワークフロー例

ダウンロードフォルダの整理

  1. フォルダをスキャンし、ファイルの分布と使用容量を確認します。

  2. 重複ファイルと古いファイルを特定します。

  3. 移動と競合をプレビューします。

  4. 確認後、カテゴリフォルダに整理します。

結果:整理されたフォルダ、重複のフラグ付け、容量の確保。

プロジェクトの整理

アシスタントがプロジェクトをスキャンし、ファイルをコード、アセット、ドキュメントに分割し、src/ ツリーを維持したまま、散在する設定ファイル、README、スクリーンショットを適切なフォルダに移動します。

重複の検出と処理

アシスタントがファイルをハッシュ化し、重複をグループ化し、各コピーを場所・名前の品質・古さでスコアリングし、保持すべきコピーと削除すべきコピーを推奨します。無駄な容量を報告します。削除するかどうかはユーザーが決定します。

大容量ファイルの発見

フォルダを指定すると、サイズ順に最大のファイルを一覧表示し、アーカイブ可能な古いバックアップをフラグし、大きな重複ファイルを通知します。

音楽の整理

ID3 タグを読み取り、フォルダを アーティスト / アルバム / タイトル.mp3 として再構築します。

Before:
Downloads/
  song1.mp3
  track02.mp3
  music_file.mp3

After:
Music/
  Coldplay/
    A Rush of Blood to the Head/
      Clocks.mp3
      The Scientist.mp3
  Radiohead/
    OK Computer/
      Paranoid Android.mp3
      Karma Police.mp3

写真の整理

EXIF から撮影日を読み取り、写真を YYYY / MM / DD フォルダに分類します。

Before:
Pictures/
  IMG_001.jpg
  photo123.png
  DSC_4567.raw

After:
Pictures/
  2023/
    12/
      25/
        IMG_001.jpg
      31/
        photo123.png
  2024/
    01/
      15/
        DSC_4567.raw

フォルダのセキュリティスクリーニング

メタデータとコンテンツ署名を抽出し、PDF 内の EXIF GPS 座標や履歴書内の個人識別子などの機密メタデータをフラグし、編集(redaction)または隔離を提案します。

自動整理の設定

ディレクトリを cron スケジュールで登録します:

{
  "directory": "/Users/john/Downloads",
  "schedule": "0 9 * * *",
  "min_file_age_minutes": 5
}

サーバーはそのスケジュールでフォルダを整理します。他のディレクトリの監視を追加することもできます。


セキュリティ設定

デフォルトでは、アクセスはユーザーディレクトリのホワイトリストに制限されています。システムディレクトリはブロックされたままです。

デフォルトで許可

サーバーは、マシン上に存在する場合、次の場所を有効にします。

プラットフォーム

許可ディレクトリ

Windows

Desktop、Documents、Downloads、Pictures、Videos、Music、OneDrive、Projects、Workspace

macOS

Desktop、Documents、Downloads、Movies、Music、Pictures、iCloud Drive、Projects

Linux

Desktop、Documents、Downloads、Music、Pictures、Videos、~/dev、~/workspace

常にブロック

これらのパスは、設定に追加してもブロックされたままです。

  • Windows: C:\Windows、Program Files、AppData、$Recycle.Bin

  • macOS: /System、/Library、/Applications、/private、/usr

  • Linux: /etc、/usr、/var、/root、/sys、/proc

  • すべての環境: node_modules、.git、.vscode、.idea、dist、build

カスタム設定

ユーザー設定ファイルを編集します。

  • Windows: %APPDATA%\file-organizer-mcp\config.json

  • macOS: $HOME/Library/Application Support/file-organizer-mcp/config.json

  • Linux: $HOME/.config/file-organizer-mcp/config.json

customAllowedDirectories にパスを追加します。

{
  "customAllowedDirectories": [
    "C:\\Users\\Name\\My Special Folder",
    "D:\\Backups"
  ]
}

ファイルエクスプローラーのアドレスバーからフォルダパスを直接貼り付けることができます。

外付けドライブとネットワークマウント

ホームディレクトリ外のパスは、オプトインしない限りブロックされます。macOS の /Volumes/My Drive や Linux の /media/user/usb などの外部ボリュームを許可するには、allowExternalVolumes を true に設定します。

{
  "allowExternalVolumes": true,
  "customAllowedDirectories": [
    "/Volumes/MyExternalDrive",
    "/Volumes/Photography Backup"
  ]
}

Windows のドライブ文字(D:\ など)は、このフラグなしで機能します。

設定編集後はクライアントを再起動してください。

競合戦略

{
  "conflictStrategy": "rename"
}
  • rename(デフォルト)- 新しいファイルに接尾辞を追加します。例:file (1).txt。

  • skip - 既存のファイルを保持し、新しいファイルをスキップします。

  • overwrite - バックアップを作成した後、既存のファイルを置き換えます。

レガシー自動整理スケジュール

シンプルな毎時・毎日・毎週のスケジュールの場合:

{
  "autoOrganize": {
    "enabled": true,
    "schedule": "daily"
  }
}

より細かいスケジュールが必要な場合は、file_organizer_watch_directory ツールを使用します。

防御

攻撃タイプ

保護

不正アクセス

ホワイトリストとブラックリストの強制

パストラバーサル

8 層の検証パイプライン

シンボリックリンク攻撃

実パス解決

DoS

ファイル数・深さ・サイズのリソース制限


トラブルシューティング

MCP サーバーが表示されない

  1. 設定ファイルのパスが正しいか確認します。

  2. Node.js 18 以降であることを確認します:node --version。

  3. クライアントを完全に再起動します。

  4. クライアント設定ファイル内のパスを確認します。

権限エラー

  • Windows:クライアントを管理者として実行します。

  • macOS/Linux:ls -la でフォルダの権限を確認します。

  • ターゲットディレクトリが書き込み可能であることを確認します。

ファイルが移動しない

  1. dry_run が有効になっていないことを確認します。

  2. ファイルをロックしている可能性のあるプログラムを閉じます。

  3. 十分なディスク容量があるか確認します。

  4. 操作サマリーのエラーメッセージを確認します。


アーキテクチャ

サーバーは、スクリーニング → エンリッチメントのパイプラインを実行します。MCP プロトコルハンドラーがすべてのリクエストをセキュリティスクリーニング(パス検証、機密ファイル検出、レート制限)に通し、次にメタデータエンリッチメント(EXIF、ID3、ドキュメントプロパティ)、そして操作を実行するサービスレイヤーに渡します。すべてのファイル操作は検証済みパスを経由し、ロールバックをサポートします。

完全な図と設計ノートについては、ARCHITECTURE.md を参照してください。


ドキュメント


コントリビューション

CONTRIBUTING.md を読み、クローンしてビルドします:

git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm test

バグや機能リクエストは GitHub Issues で報告してください。セキュリティの脆弱性については、technocratix902@gmail.com までメールでご連絡ください。

ライセンス

MIT。 LICENSE を参照してください。

Available Tools

26 tools
file_organizer_analyze_duplicatesAnalyze Duplicate Files with Smart RecommendationsC
Read-onlyIdempotent

Finds duplicate files and suggests which to keep/delete based on location, name quality, and age.

Inputs: directory (required), response_format, auto_select_keep, recommendation_strategy.

file_organizer_batch_read_filesBatch Read Files for LLM ContextA
Read-onlyIdempotent

Reads contents of all files in a specified folder for LLM context. For text files (documents, code, notes), reads the actual content. For media files (audio, video, images), reads metadata instead of binary content. Provides a comprehensive summary of folder contents.

Inputs: directory (required), max_files, file_types, include_content, +4 more.

file_organizer_batch_renameBatch Rename FilesA
Destructive

Rename multiple files using rules (find/replace, case, add text, numbering). "dry_run" defaults to true for safety.

Inputs: rules (required), files, dry_run, directory, +1 more.

file_organizer_categorize_by_typeCategorize Files by TypeA
Read-onlyIdempotent

Categorize files by their type (Executables, Videos, Documents, etc.) and show statistics for each category. Enable use_content_analysis to detect file type mismatches and security threats.

Inputs: directory (required), include_subdirs, response_format, use_content_analysis.

file_organizer_delete_duplicatesDelete Duplicate FilesB
Destructive

Permanently deletes specified duplicate files. DESTRUCTIVE. Verifies hash/size before deletion.

Inputs: files_to_delete (required), response_format, create_backup_manifest.

file_organizer_find_duplicate_filesFind Duplicate FilesB
Read-onlyIdempotent

Find duplicate files in a directory based on their content (SHA-256 hash). Shows potential wasted space.

Inputs: directory (required), limit, offset, response_format.

file_organizer_find_largest_filesFind Largest FilesA
Read-onlyIdempotent

Find the largest files in a directory. Useful for identifying space-consuming files and cleanup opportunities.

Inputs: directory (required), top_n, include_subdirs, response_format.

file_organizer_get_categoriesGet Available File CategoriesA
Read-onlyIdempotent

Returns the list of categories used for file organization

Inputs: response_format.

file_organizer_inspect_metadataInspect File MetadataA
Read-onlyIdempotent

Inspects a file and returns comprehensive but privacy-safe metadata. For images, extracts EXIF data (date, camera, dimensions). For audio, extracts ID3 tags (artist, album, title). Excludes sensitive data like GPS coordinates.

Inputs: file (required), response_format.

file_organizer_list_filesList Files in DirectoryA
Read-onlyIdempotent

List all files in a directory with basic information. Returns file names and paths. Does not recurse into subdirectories.

Inputs: directory (required), limit, offset, response_format.

file_organizer_list_watchesList Watched DirectoriesA
Read-onlyIdempotent

List all directories currently being watched with their schedules.

Inputs: response_format.

file_organizer_organize_by_contentOrganize Documents by ContentA
Destructive

Organize files based on content analysis. strategy='topic' groups documents (PDF, DOCX, TXT, MD, RTF, ODT) into topic-based folders. strategy='project' groups files across all types (documents, code, images) into detected project folders using shared name tokens, content terms, and identifiers. Use dry_run=true to preview changes.

Inputs: source_dir (required), target_dir (required), dry_run, strategy, +3 more.

file_organizer_organize_filesOrganize FilesC
Destructive

Automatically organize files into categorized folders. Enable use_content_analysis to detect file type mismatches and potential security threats. Use dry_run=true to preview changes.

Inputs: directory (required), dry_run, response_format, conflict_strategy, +1 more.

file_organizer_organize_musicOrganize Music FilesB
Destructive

Organize music files into structured folders based on metadata (Artist/Album). Supports MP3, FLAC, OGG, WAV, M4A, AAC. Use dry_run=true to preview changes.

Inputs: source_dir (required), target_dir (required), dry_run, structure, +4 more.

file_organizer_organize_photosOrganize Photo FilesA
Destructive

Organize photos into date-based folders using EXIF metadata. Supports JPG, PNG, TIFF, HEIC, RAW formats. Can group by camera model and strip GPS data for privacy. Use dry_run=true to preview changes.

Inputs: source_dir (required), target_dir (required), dry_run, strip_gps, +5 more.

file_organizer_organize_smartSmart Organize FilesA
Destructive

Automatically organizes mixed files (music, photos, documents) using the appropriate strategy for each type. Music → Artist/Album structure. Photos → Date-based folders with optional GPS stripping. Documents → Topic-based folders. Use dry_run=true to preview changes.

Inputs: source_dir (required), target_dir (required), dry_run, recursive, +6 more.

file_organizer_preview_organizationPreview File Organization PlanA
Read-onlyIdempotent

Shows what would happen if files were organized, WITHOUT making any changes. Shows moves, conflicts, and skip reasons.

Inputs: directory (required), response_format, conflict_strategy, show_conflicts_only.

file_organizer_read_fileRead File ContentsA
Read-onlyIdempotent

Read file contents with security checks. Supports text, binary, and base64 encoding. Automatically detects file type and applies appropriate security validations. Sensitive files (passwords, keys, credentials) are automatically blocked.

Inputs: path (required), limit, offset, encoding, +3 more.

file_organizer_scan_directoryScan Directory for Detailed InfoB
Read-onlyIdempotent

Scan directory and get detailed file information including size, dates, and extensions. Supports recursive scanning and security screening.

Inputs: directory (required), limit, offset, max_depth, +3 more.

file_organizer_set_custom_rulesSet Custom Organization RulesB

Customize how files are categorized. Rules persist for the current session.

Inputs: rules (required).

file_organizer_smart_suggestSmart SuggestC
Read-onlyIdempotent

Analyze directory health and get actionable suggestions for organization

Inputs: directory (required), max_files, use_cache, sample_rate, +4 more.

file_organizer_system_organizeSystem OrganizeC
Destructive

Organize files into OS-standard system directories (Music, Documents, Pictures, Videos)

Inputs: source_dir (required), dry_run, response_format, use_system_dirs, +5 more.

file_organizer_undo_last_operationUndo Last Organization OperationC
Destructive

Reverses file moves and renames from a previous organization task.

Inputs: manifest_id, response_format.

file_organizer_unwatch_directoryUnwatch DirectoryB
Idempotent

Remove a directory from the watch list.

Inputs: directory (required), response_format.

file_organizer_view_historyView HistoryA
Read-onlyIdempotent

View the history of file organization operations. Supports filtering by date range, operation type, status, and source. Use privacy_mode to control output detail level.

Inputs: limit, since, until, source, +4 more.

file_organizer_watch_directoryWatch DirectoryA
Idempotent

Add a directory to the watch list with a cron-based schedule for automatic organization. When the user specifies a schedule in natural language (e.g., "every day at 10am"), convert it to a standard cron expression. Cron format: "minute hour day month weekday". Common conversions: "every day at 10am" → "0 10 * * ", "every 30 minutes" → "/30 * * * *", "every Monday at 9am" → "0 9 * * 1", "every hour" → "0 * * * *".

Inputs: schedule (required), directory (required), auto_organize, response_format, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 26 tools

    Disambiguation3/5

    There is significant overlap among tools, e.g., organize_files vs organize_smart vs organize_by_content vs system_organize, and find_duplicate_files vs analyze_duplicates. Descriptions help differentiate them, but an agent could easily pick the wrong one for a given task.

    Naming Consistency5/5

    All 26 tools follow the consistent 'file_organizer_verb_noun' pattern, with clear verbs like list, scan, organize, read, watch. This is highly predictable and easy to navigate.

    Tool Count3/5

    With 26 tools, the server is slightly above the 15-25 range. The broad feature set (organizing, watching, metadata, history) justifies many tools, but the count feels bloated, especially with overlapping functions that could be consolidated.

    Completeness4/5

    The tool set covers listing, scanning, categorization, duplicate detection, multiple organization strategies, preview, history, watching, renaming, and metadata inspection. Missing direct file deletion (except duplicates) and file editing, but those are outside the organizer's scope. Overall coverage is strong with minor gaps.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Comprehensive MCP server for filesystem operations, process management, interactive sessions, and async file search. Includes utilities for JSON repair, encoding fixes, duplicate detection, OCR, ZIP archives, and Markdown export.
      50
      205 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.
      19
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      A full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools. Fully compliant with the official Model Context Protocol specification, offering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and comprehensive text search & replace functionality for LLM agent integration.
      22
      17 PyPI
      Apache 2.0