File Organizer MCP
File Organizer MCP Server
버전 3.5.0 | MCP 프로토콜 2024-11-05 | Node.js 18+
파일을 정리하는 Model Context Protocol (MCP) 서버입니다. 이 서버는 Claude 스타일 어시스턴트가 수십 개의 기본 read, write, rename 호출을 연결하는 대신, 파일을 분류하고 정렬하며 중복을 제거하고 이름을 바꾸는 단일 원자적 작업을 제공합니다.
왜 필요한가
read, write, make, delete만으로 구축된 파일시스템 MCP 서버는 어시스턴트가 모든 이동과 이름 변경을 별도의 단계로 계획해야 합니다. 각 단계는 토큰을 소비하며, 단계가 많을수록 경로를 잘못 지정할 가능성이 높아집니다.
File Organizer MCP는 이러한 체인을 단 한 번의 호출로 대체합니다:
기본 접근 방식 | File Organizer MCP |
많은 |
|
수십 개의 추론 단계 | 단 하나의 추론 단계 |
높은 토큰 사용량 | 최소 토큰 사용량 |
부분 실패 시 손상되기 쉬움 | 롤백 안전 작업 |
Related MCP server: MCP Filesystem Agent v3
빠른 시작
원커맨드 설정
npx file-organizer-mcp --setup마법사는 설치된 AI 클라이언트(Claude Desktop, Cursor, Windsurf, Cline 등)를 감지하여 구성하고, 폴더 선택과 기본 설정을 안내합니다.
요구 사항
Node.js 18 이상.
설정 후
어시스턴트에게 다음과 같은 요청을 할 수 있습니다:
"내 다운로드 폴더를 정리해 줘"
"내 문서에서 중복 파일을 찾아 줘"
"가장 큰 파일들을 보여 줘"
설치 방법
방법 | 명령어 | 사용 사례 |
npx |
| 가끔 사용 또는 체험판 |
전역 설치 |
| 정기 사용, 더 빠른 시작 |
기능
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_duplicatesfile_organizer_batch_read_filesfile_organizer_categorize_by_typefile_organizer_delete_duplicatesfile_organizer_find_duplicate_filesfile_organizer_find_largest_filesfile_organizer_get_categoriesfile_organizer_inspect_metadatafile_organizer_list_filesfile_organizer_list_watchesfile_organizer_organize_by_contentfile_organizer_organize_filesfile_organizer_organize_musicfile_organizer_organize_photosfile_organizer_preview_organizationfile_organizer_read_filefile_organizer_scan_directoryfile_organizer_set_custom_rulesfile_organizer_smart_suggestfile_organizer_system_organizefile_organizer_undo_last_operationfile_organizer_unwatch_directoryfile_organizer_view_historyfile_organizer_watch_directory
매개변수와 반환 형식에 대해서는 API.md를 참조하세요.
파일 카테고리
카테고리 | 일반적인 확장자 |
실행 파일 |
|
비디오 |
|
문서 |
|
이미지 |
|
오디오 |
|
압축 파일 |
|
코드 |
|
예제 워크플로우
다운로드 폴더 정리
폴더를 스캔하고 파일 분포와 공간 사용량을 검토합니다.
중복 파일과 오래된 파일을 식별합니다.
이동 및 충돌을 미리 봅니다.
확인 후 카테고리 폴더로 정리합니다.
결과: 정렬된 폴더, 중복 파일 표시, 확보된 공간.
프로젝트 정리
어시스턴트가 프로젝트를 스캔하고 파일을 코드, 에셋, 문서로 분리하며 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, |
항상 차단
다음 경로는 구성에 추가하더라도 계속 차단됩니다:
Windows:
C:\Windows, Program Files, AppData,$Recycle.BinmacOS:
/System,/Library,/Applications,/private,/usrLinux:
/etc,/usr,/var,/root,/sys,/proc모든 곳:
node_modules,.git,.vscode,.idea,dist,build
사용자 지정 구성
사용자 구성 파일을 편집합니다:
Windows:
%APPDATA%\file-organizer-mcp\config.jsonmacOS:
$HOME/Library/Application Support/file-organizer-mcp/config.jsonLinux:
$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 서버가 표시되지 않음
구성 파일 경로가 올바른지 확인합니다.
Node.js 18 이상인지 확인합니다:
node --version.클라이언트를 완전히 다시 시작합니다.
클라이언트 구성 파일의 경로를 확인합니다.
권한 오류
Windows: 클라이언트를 관리자로 실행합니다.
macOS/Linux:
ls -la로 폴더 권한을 확인합니다.대상 디렉토리가 쓰기 가능한지 확인합니다.
파일이 이동되지 않음
dry_run이 활성화되어 있지 않은지 확인합니다.파일을 잠글 수 있는 프로그램을 닫습니다.
충분한 디스크 공간이 있는지 확인합니다.
오류 메시지가 있는지 작업 요약을 읽습니다.
아키텍처
서버는 스캔 후 강화 파이프라인을 실행합니다: MCP 프로토콜 핸들러가 모든 요청을 보안 검사(경로 검증, 민감 파일 감지, 속도 제한)를 통과시킨 다음, 메타데이터 강화(EXIF, ID3, 문서 속성), 그 다음 작업을 수행하는 서비스 계층으로 전달합니다. 모든 파일 작업은 검증된 경로를 통해 이루어지며 롤백을 지원합니다.
전체 다이어그램과 설계 노트는 ARCHITECTURE.md를 참조하세요.
문서
API.md - 전체 도구 참조
ARCHITECTURE.md - 설계 및 아키텍처
CONTRIBUTING.md - 기여 지침
MIGRATION.md - v2에서 v3 업그레이드 가이드
CHANGELOG.md - 버전 기록
SECURITY.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 toolsfile_organizer_analyze_duplicatesAnalyze Duplicate Files with Smart RecommendationsCRead-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 ContextARead-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 FilesADestructive
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 TypeARead-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 FilesBDestructive
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 FilesBRead-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 FilesARead-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 CategoriesARead-onlyIdempotent
Returns the list of categories used for file organization
Inputs: response_format.
file_organizer_inspect_metadataInspect File MetadataARead-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 DirectoryARead-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 DirectoriesARead-onlyIdempotent
List all directories currently being watched with their schedules.
Inputs: response_format.
file_organizer_organize_by_contentOrganize Documents by ContentADestructive
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 FilesCDestructive
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 FilesBDestructive
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 FilesADestructive
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 FilesADestructive
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 PlanARead-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 ContentsARead-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 InfoBRead-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 SuggestCRead-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 OrganizeCDestructive
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 OperationCDestructive
Reverses file moves and renames from a previous organization task.
Inputs: manifest_id, response_format.
file_organizer_unwatch_directoryUnwatch DirectoryBIdempotent
Remove a directory from the watch list.
Inputs: directory (required), response_format.
file_organizer_view_historyView HistoryARead-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 DirectoryAIdempotent
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseBqualityBmaintenanceComprehensive 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.50205 npm6MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server enabling Claude and other LLMs to perform intelligent file operations with minimal token usage.MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.19MIT
- AlicenseCqualityCmaintenanceA 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.2217 PyPIApache 2.0