Skip to main content
Glama
File Organizer MCP

File Organizer MCP

by kridaydave

File Organizer MCP Server

버전 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는 이러한 체인을 단 한 번의 호출로 대체합니다:

기본 접근 방식

File Organizer MCP

많은 read / write / rename 호출

organize_files()가 전체 이동을 원자적으로 실행

수십 개의 추론 단계

단 하나의 추론 단계

높은 토큰 사용량

최소 토큰 사용량

부분 실패 시 손상되기 쉬움

롤백 안전 작업


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 - 음악, 사진, 문서를 한 번에 처리하며 파일별 최적의 전략을 선택합니다.

  • 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 좌표나 이력서의 개인 식별 정보와 같은 민감한 메타데이터를 표시하고, 삭제 또는 격리를 제안합니다.

자동 정리 설정

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