Photo Organizer MCP

🚀 Photo Organizer MCP Server

AI-powered organization for Google Photos and Google Drive.

This MCP server empowers AI agents such as Claude to automatically organize your Google Photos and Drive files. It's ideal for decluttering cloud storage, finding duplicates, and maintaining well - organized photo albums.

🚀 Quick Start

This MCP server allows AI agents to organize your Google Photos and Drive files. To get started, follow the installation and setup steps below.

✨ Features

Google Photos

• 📊 Analyze Library: Obtain statistics and insights regarding your photo collection.
• 🔍 Find Duplicates: Identify potential duplicate photos.
• 📅 Auto - Organize: Create albums by year or month.
• 📈 Reports: Generate detailed organization reports.

Google Drive

• 📂 Auto - Organize: Sort files into folders by type (Documents, Images, Videos, etc.).
• 🗄️ Archive Old Files: Move old files to the Archive folder.
• 🔄 Deduplicate: Find and remove exact duplicate files.
• 📊 Analytics: Get file statistics and storage insights.

📦 Installation

# Install from NPM
npm install -g photo-organizer-mcp

# Or clone and build
git clone https://github.com/ExpertVagabond/photo-organizer-mcp
cd photo-organizer-mcp
npm install
npm run build

📚 Documentation

1. Google Cloud Credentials

You need Google Cloud credentials to access the Photos and Drive APIs:

1. Navigate to Google Cloud Console.
2. Create a new project.
3. Enable the Google Photos Library API and Google Drive API.
4. Create OAuth 2.0 credentials.
5. Download credentials.json.

2. Python Scripts

This MCP server wraps existing Python organizer scripts. Set the path:

export PHOTO_SCRIPTS_PATH="/path/to/drive-photos-organizer"

Or add it to .env:

PHOTO_SCRIPTS_PATH=/Users/yourname/drive-photos-organizer

3. Configure Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "photo-organizer": {
      "command": "photo-organizer-mcp",
      "env": {
        "PHOTO_SCRIPTS_PATH": "/path/to/drive-photos-organizer"
      }
    }
  }
}

💻 Usage Examples

With Claude

Basic Usage

"Analyze my Google Photos and find duplicates"

Claude will use the analyze_photos tool to scan your library

"Organize my photos into albums by year"

Claude will create year-based albums (dry run first, then execute)

"Clean up my Google Drive by organizing files into folders"

Claude will sort files by type into organized folders

"Archive all Drive files older than 2 years"

Claude will move old files to an Archive folder

"Find and remove duplicate files from my Drive"

Claude will identify and remove exact duplicates

Available Tools

Photo Tools

1. analyze_photos - Get photo library statistics

   {
     "findDuplicates": true
   }
   

2. organize_photos_by_date - Create date-based albums

   {
     "grouping": "year",  // or "month"
     "execute": false     // true to actually create albums
   }
   

Drive Tools

3. analyze_drive - Get Drive statistics

4. organize_drive - Sort files into folders

   {
     "execute": false  // true to actually organize
   }
   

5. archive_old_files - Move old files to Archive

   {
     "days": 730,      // Archive files older than this
     "execute": false
   }
   

6. deduplicate_drive - Remove duplicate files

   {
     "execute": false  // true to actually delete
   }
   

Safety Features

• Dry Run by Default: All operations default to dry run mode.
• Explicit Execution: You must set execute: true to make changes.
• Detailed Reports: You can see exactly what will happen before executing.
• Non - Destructive: It organizes and archives, doesn't delete (except for deduplication).

Monetization (Pro Version)

Upgrade for advanced features:

Free Tier

• 50 operations per month.
• Basic organization.
• Manual execution required.

Pro ($10/month)

• Unlimited operations.
• Scheduled auto - organization.
• Advanced duplicate detection.
• Priority support.

Enterprise ($50/month)

• White - label branding.
• Team management.
• Custom rules engine.
• API access.

🔧 Technical Details

• Built with TypeScript and Model Context Protocol SDK.
• Wraps Python scripts for Google API integration.
• Async operation with progress reporting.
• Handles large libraries (10,000+ photos).

Contributing

Contributions are welcome! Please open issues or PRs on GitHub.

📄 License

MIT License - see LICENSE file

Author

ExpertVagabond - https://github.com/ExpertVagabond

Need help? Contact: hello@expertvagabond.com