io.github.ExpertVagabond/photo-organizer

Official

by ExpertVagabond · Rust

AI-powered organization for Google Photos and Drive - auto-organize, find duplicates, create albums

Automatically organize Google Photos and Drive, detect duplicates, and create albums using AI.

Topics

ai-toolsgoogle-photosmcpmcp-serveraimodel-context-protocoltools

README.md4 KBView on GitHub

Photo Organizer MCP Server

AI-powered organization for Google Photos and Google Drive.

This MCP server enables AI agents like Claude to automatically organize your Google Photos and Drive files. Perfect for decluttering cloud storage, finding duplicates, and maintaining organized photo albums.

Features

Google Photos

📊 Analyze Library: Get statistics and insights about 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 Archive folder
🔄 Deduplicate: Find and remove exact duplicate files
📊 Analytics: Get file statistics and storage insights

Installation

bash

# 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

Setup

1. Google Cloud Credentials

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

Go to Google Cloud Console
Create a new project
Enable Google Photos Library API and Google Drive API
Create OAuth 2.0 credentials
Download credentials.json

2. Python Scripts

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

bash

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

Or add to .env:

code

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

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

json

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

Usage Examples

With Claude

"Analyze my Google Photos and find duplicates"

code

Claude will use the analyze_photos tool to scan your library

"Organize my photos into albums by year"

code

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

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

code

Claude will sort files by type into organized folders

"Archive all Drive files older than 2 years"

code

Claude will move old files to an Archive folder

"Find and remove duplicate files from my Drive"

code

Claude will identify and remove exact duplicates

Available Tools

Photo Tools

analyze_photos - Get photo library statistics
json
```
{
  "findDuplicates": true
}
```

organize_photos_by_date - Create date-based albums

json

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

Drive Tools

analyze_drive - Get Drive statistics

organize_drive - Sort files into folders

json

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

archive_old_files - Move old files to Archive

json

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

deduplicate_drive - Remove duplicate files

json

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

Safety Features

Dry Run by Default: All operations default to dry run mode
Explicit Execution: Must set execute: true to make changes
Detailed Reports: See exactly what will happen before executing
Non-Destructive: Organizes and archives, doesn't delete (except 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 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

Install

Configuration

Environment variables

PHOTO_SCRIPTS_PATHrequired

Path to Python scripts directory containing drive_organizer.py and photos_organizer.py

claude_desktop_config.json

{
  "mcpServers": {
    "photo-organizer": {
      "command": "npx",
      "args": [
        "-y",
        "photo-organizer-mcp@1.0.0"
      ],
      "env": {
        "PHOTO_SCRIPTS_PATH": "<YOUR_PHOTO_SCRIPTS_PATH>"
      }
    }
  }
}