AutoOrganizerMCP

An MCP (Model Context Protocol) server that automatically organizes files in a directory — sorting them into subfolders by type and renaming them based on content analysis.

Features

• Scans a directory and lists all files with type and size
• Moves files into subfolders based on file extension
• Renames files using AI content analysis (pluggable — ready for OpenAI or any LLM)
• Handles filename collisions automatically (file, file_1, file_2, ...)
• Exposes all functionality as MCP tools, usable by any MCP client (e.g. Claude Desktop)

Supported File Types

Extension	Subfolder
.jpg, .png	images
.txt, .pdf, .docx, .xlsx, .csv	documents
.mp3, .wav	audio
.mp4	video
anything else	others

Requirements

• Python 3.11+
• Dependencies listed in pyproject.toml

Setup

# with uv (recommended)
uv sync

# or with pip
pip install fastmcp python-dotenv pydantic

Create a .env file in the project root for any environment variables.

Running the Server

python main.py

MCP Tools

Tool	Description
scan_directory_and_list_files	Lists all files in a folder with name, type, and size
organize_files	Moves files into type-based subfolders and renames them
create_folders_and_move_files	Same as organize_files — moves and renames files
change_file_names	Renames files in-place based on AI content analysis

Project Structure

AutoOrganizerMCP/
├── main.py                  # MCP server entry point & tool definitions
├── settings.py              # Environment/config loader
├── services/
│   ├── organizer_service.py # Core organize logic (scan → rename → move)
│   ├── ai_service.py        # Filename generation (plug in your LLM here)
│   └── file_service.py      # File rename operations
├── models/
│   ├── file_model.py        # File data model
│   └── result.py            # Standardized tool result model
├── utils/
│   ├── file_utils.py        # Scan, move, create directory
│   ├── text_utils.py        # Filename sanitization
│   └── errors.py            # Error codes
└── tests/
    └── test_organizer.py    # Unit tests

Connecting an LLM for Smarter Renaming

Open services/ai_service.py and replace the stub logic in generate_new_filename with a call to OpenAI or any other model:

def generate_new_filename(self, file: FileModel) -> str:
    # plug in your LLM call here
    return file.name.lower()

Running Tests

python -m pytest tests/ -v