file-organizer-MCP-Server

file-organizer-MCP-Server

3.1
file_systems

If you are the rightful owner of file-organizer-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

File Organizer MCP Server uses Google's Gemini Vision API to analyze screenshots and organize files based on extracted order.

File Organizer MCP Server

A Model Context Protocol (MCP) server that uses Google's Gemini Vision API to analyze screenshots of file listings/course contents and automatically organize files based on the extracted order.

Features

  • Screenshot Analysis: Uses Gemini Vision API to extract file organization order from screenshots
  • Smart File Organization: Matches files with extracted order and renames them with numeric prefixes
  • Descriptive Folders: Creates section-specific folders based on content type
  • AI/OCR Handling: Robust handling of common OCR variations (e.g., AI vs Al)
  • Undo Support: Can revert organized files back to their original state

Prerequisites

  • Python 3.13+
  • Visual Studio Code
  • Google API key for Gemini Vision API
  • MCP Extension for VS Code
  • uv package manager (recommended) or pip

Setup

  1. Clone the repository:
git clone https://github.com/mutaician/file-organizer-MCP-Server.git
cd file-organizer-mcp
  1. Create and activate virtual environment using uv:
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

  1. Install VS Code MCP Extension:

    • Open VS Code
    • Go to Extensions (Ctrl+Shift+X)
    • Install the GitHub Copilot extension (or any extension that supports MCP servers).

  2. Configure VS Code workspace:

    • Create .vscode folder if it doesn't exist
    • Add mcp.json with the following content:
    {
  "inputs": [
    {
      "type": "promptString",
      "id": "gemini-key",
      "description": "Gemini API Key",
      "password": true
    }
  ],
  "servers": {
    "File Organizer": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["${workspaceFolder}/src/server.py"],
      "env": {
        "GOOGLE_API_KEY": "${input:gemini-key}"
      }
    }
  }
}

Usage in VS Code

  1. Start the MCP Server:

    • Open Command Palette (Ctrl+Shift+P)
    • Type "MCP: List Servers"
    • Select "File Organizer"
    • Enter your Gemini API key when prompted
    • You should now see your server and its tools available in the Copilot Chat/Agent mode.

  2. In the Copilot Chat, you can organize your files by:

    • First, analyze a screenshot to get the file order: 
      Could you analyze the screenshot at "/path/to/screenshot.jpg"?
    • Then organize files using the extracted order: 
      Could you organize the files in "/path/to/section" using this order?
    • The server will automatically:
      • Create a descriptive subfolder based on the section title
      • Number files according to their order
      • Handle AI/OCR variations

  3. Additional Commands:

    • List files in a directory: 
      Could you list the files in "/path/to/directory"?
    • Undo organization: 
      Could you undo the organization from "/path/to/organized" back to "/path/to/source"?

  4. Best Practices:

    • Keep screenshots clear and well-lit for better OCR
    • Verify organization results after each operation
    • Use the undo function if needed before trying again

Key Concepts

  1. Screenshot Analysis:

    • Takes a screenshot of your desired file organization (e.g., course content listing)
    • Uses Gemini Vision to extract the order and hierarchy
    • Handles numbered lists and various formats

  2. File Organization:

    • Matches files to the extracted order
    • Adds numeric prefixes (e.g., "01_", "02_")
    • Creates descriptive subfolders based on content type
    • Preserves original filenames after the prefix

  3. Smart Matching:

    • Handles variations in OCR text (AI vs Al)
    • Ignores case sensitivity
    • Removes special characters that might interfere
    • Matches partial names when appropriate

Troubleshooting

  • If files aren't matching correctly:

    • Check for special characters in filenames
    • Verify the screenshot text is clear and readable
    • Ensure file extensions are correct

  • If the server won't start:

    • Verify your Gemini API key is valid
    • Check Python virtual environment is activated
    • Ensure all dependencies are installed

Dependencies

  • mcp-sdk: Model Context Protocol implementation
  • google-generativeai: Gemini AI API client
  • pillow: Image processing for screenshots

Related MCP Servers

View all file_systems servers →
markdownify-mcp

markdownify-mcp

4.6

by zcaceres

Markdownify is a Model Context Protocol (MCP) server that converts various file types and web content to Markdown format.

file_systems
excel-mcp-server

excel-mcp-server

4.5

by haris-musa

A Model Context Protocol (MCP) server that lets you manipulate Excel files without needing Microsoft Excel installed.

file_systems
excel-mcp-server

excel-mcp-server

4.3

by negokaz

A Model Context Protocol (MCP) server that reads and writes MS Excel data.

file_systems
edgeone-pages-mcp

edgeone-pages-mcp

4.2

by TencentEdgeOne

An MCP service for deploying HTML content, folder, and zip file to EdgeOne Pages and obtaining a publicly accessible URL.

cloud_platforms
claude-code-mcp

claude-code-mcp

3.7

by steipete

An MCP (Model Context Protocol) server that allows running Claude Code in one-shot mode with permissions bypassed automatically.

developer_tools
filesystem

filesystem

3.7

by javillegasna

Python server implementing Model Context Protocol (MCP) for filesystem operations.

file_systems
obsidian-mcp-tools

obsidian-mcp-tools

3.6

by jacksteamdev

MCP Tools for Obsidian enables AI applications like Claude Desktop to securely access and work with your Obsidian vault through the Model Context Protocol (MCP).

ai_chatbot
moling

moling

3.6

by gojue

MoLing is a dependency-free local office automation assistant that interacts with the system through operating system APIs, enabling file system operations and command execution.

os_automation
claude-code-mcp

claude-code-mcp

3.6

by auchenberg

Claude Code MCP is an implementation of Claude Code as a Model Context Protocol (MCP) server, enabling its software engineering capabilities through a standardized interface.

developer_tools
applescript-mcp

applescript-mcp

3.6

by joshrutkowski

A Model Context Protocol server that enables LLM applications to interact with macOS through AppleScript, providing a standardized interface for AI applications to control system functions, manage files, handle notifications, and more.

os_automation
mcp-apple-notes

mcp-apple-notes

3.6

by RafalWilinski

A Model Context Protocol (MCP) server that enables semantic search and RAG over Apple Notes, allowing AI assistants like Claude to search and reference notes during conversations.

knowledge_and_memory
mcp-everything-search

mcp-everything-search

3.6

by mamertofabian

An MCP server that provides fast file searching capabilities across Windows, macOS, and Linux.

file_systems
mcp-text-editor

mcp-text-editor

3.6

by tumf

A Model Context Protocol (MCP) server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.

file_systems
mcp-client-server-markdown

mcp-client-server-markdown

3.6

by zou-hong-run

MCP Markdown Server is a server application based on the Model Context Protocol (MCP) that provides functionalities for creating, editing, searching, converting to HTML, and managing Markdown documents.

file_systems
notes-mcp

notes-mcp

3.5

by krasun

An MCP server that connects with your Apple Notes on macOS.

file_systems
mcp-excel-server

mcp-excel-server

3.5

by yzfly

An MCP server that provides comprehensive Excel file management and data analysis capabilities.

file_systems
obsidian-mcp-rest

obsidian-mcp-rest

3.5

by PublikPrinciple

An MCP server implementation that provides access to Obsidian vaults through a local REST API.

file_systems
aws-sa-tools-mcp-server

aws-sa-tools-mcp-server

3.5

by Havoc24k

A Model Context Protocol (MCP) server that provides tools to interact with AWS services.

cloud_platforms
vertex-ai-mcp-server

vertex-ai-mcp-server

3.5

by shariqriazz

This project implements a Model Context Protocol (MCP) server that provides a comprehensive suite of tools for interacting with Google Cloud's Vertex AI Gemini models, focusing on coding assistance and general query answering.

ai_chatbot
mcp-server-multiverse

mcp-server-multiverse

3.5

by lamemind

A middleware server that enables multiple isolated instances of the same MCP servers to coexist independently with unique namespaces and configurations.

file_systems
OpenSCAD-MCP-Server

OpenSCAD-MCP-Server

3.5

by jhacksman

A Model Context Protocol (MCP) server that enables users to generate 3D models from text descriptions or images, with a focus on creating parametric 3D models using multi-view reconstruction and OpenSCAD.

cloud_platforms
gdrive-mcp-server

gdrive-mcp-server

3.5

by felores

A powerful Model Context Protocol (MCP) server that provides seamless integration with Google Drive, allowing AI models to search, list, and read files from Google Drive.

file_systems
wordpress-mcp-server

wordpress-mcp-server

3.5

by prathammanocha

A comprehensive Model Context Protocol (MCP) server for interacting with WordPress sites via the REST API.

communication
mcp-filesystem

mcp-filesystem

3.5

by safurrier

A powerful Model Context Protocol (MCP) server for filesystem operations optimized for intelligent interaction with large files and filesystems.

file_systems
ebook-mcp

ebook-mcp

3.5

by onebirdrocks

Ebook-MCP is a Model Context Protocol server designed for processing electronic books, supporting EPUB and PDF formats.

file_systems
paperless-mcp

paperless-mcp

3.5

by nloui

An MCP server for managing documents, tags, correspondents, and document types in Paperless-NGX.

file_systems
file_analysis_mcp

file_analysis_mcp

3.5

by JustVarunsai

File Analysis MCP Server is a custom-built Model Context Protocol server designed for text file analysis, available as a package on PyPI.

file_systems