immich-photo-manager

📸🧹🗺️ MCP server for intelligent photo management with Immich — your self-hosted library, understood.

If you self-host Immich and your library has grown past the point where you can manage it by hand, immich-photo-manager gives Claude direct access to your Immich instance through 21 MCP tools and 11 specialized skills — from finding cross-ecosystem duplicates with perceptual hashing to generating interactive HTML galleries with a Cowork Actions Panel.

🚀 Quick Start

Prerequisites

• A running Immich instance (self-hosted, v1.90+)
• An Immich API key (how to create one)
• Python 3.10+ with pip (download)

Option A: Install as Claude Plugin (recommended)

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager

# Register the marketplace and install
claude plugin marketplace add .
claude plugin install immich-photo-manager

Verify with claude plugin list.

That's it. Open Claude and say "how healthy is my photo library?" to get started.

Note: The plugin connects to your Immich MCP server at localhost:8626. Make sure the server is running before using the plugin. See Option B for how to build and start the server.

Option B: Manual MCP Server Setup

If you prefer to configure the MCP server manually instead of using the setup script:

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt

Create .mcp.json in the project root:

{
  "mcpServers": {
    "immich": {
      "command": "python3",
      "args": ["-m", "immich_mcp_server"],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/immich-photo-manager/src",
        "MCP_TRANSPORT": "stdio",
        "IMMICH_BASE_URL": "https://your-immich-server.com",
        "IMMICH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important: Use PYTHONPATH pointing to the src/ directory. Do NOT use cwd (it is silently ignored by Claude Code).

Note on Smart Search (CLIP): The search_smart tool requires the Immich machine learning service to be running and Smart Search enabled in Administration > Settings > Machine Learning Settings > Smart Search. If the ML service is not configured, the tool will return a helpful error message instead of failing silently. All other tools work without the ML service. See the Immich Smart Search docs for setup details.

🎬 Core Workflow

You: "Create albums for all the places I've traveled"

→ Scans GPS data from 28,000+ photos
→ Clusters by location, identifies 47 destinations across 14 countries
→ Proposes album list for approval
→ Creates albums with curated selections (20-50 photos each)
→ Publishes to Gallery with shared links

✅ Created: 🇮🇹 Roma, Italia (47 photos, Jun 2023)
✅ Created: 🇪🇬 Cairo & Luxor, Egypt (63 photos, Mar 2024)
✅ Created: 🇲🇽 Oaxaca, México (38 photos, Dec 2022)
... 44 more albums

Geographic album creation combines GPS coordinates, CLIP visual search, and temporal matching — then filters out screenshots and duplicates automatically. One request, dozens of curated albums.

✨ Features

🖼️ Interactive Gallery & Cowork Actions

Say "show me photos from Barcelona" and the plugin generates a self-contained HTML gallery — no server required, opens in any browser.

You: "Show me my Egypt album"

→ Fetches album + base64 thumbnails from Immich
→ Generates single-file HTML with embedded images
→ 3 themes (light/system/dark), 4 view modes, slideshow, keyboard nav
→ Cowork Actions Panel for batch operations

✅ egypt-album.html — open it, browse your photos, select & act

The Cowork Actions Panel is a sticky toolbar inside each gallery. Select photos, then click any action — the command is copied to your clipboard, ready to paste into Cowork chat:

The gallery is fully responsive, works offline once generated, and supports touch gestures on mobile.

🤔 Why immich-photo-manager?

Immich is excellent at storing, viewing, and searching your photos. But managing a large library — deduplication, metadata repair, album curation, storage analysis — still requires manual effort or custom scripts. immich-photo-manager bridges that gap.

🧩 Skills

Skills are specialized workflows that combine MCP tools with domain knowledge. Each handles a specific photo management task end-to-end.

See the Skills Reference for detailed workflows, triggers, and output formats.

⚙️ How It Works

Claude ←→ MCP (stdio) ←→ Python Server ←→ Immich REST API
                                              your-instance

The MCP server is a Python module (immich_mcp_server) that communicates with Claude over stdio transport. It exposes 21 tools that map to Immich REST API endpoints, with added intelligence for batch operations, thumbnail embedding, and credential management.

Gallery HTML files are fully self-contained — thumbnails are fetched from Immich, encoded as base64, and embedded directly in the HTML. This is required because the Cowork viewer runs in an about: sandbox that blocks all external network requests. See Architecture for the full technical explanation.

21 MCP Tools

See the MCP Tools Reference for parameters, return types, and examples.

📚 Documentation

Additional dependencies (optional)

Some advanced skills require Python packages or direct database access:

pip3 install Pillow imagehash pillow-heif

🤝 Contributing

Contributions are welcome. If you find a bug, have a feature idea, or want to improve a skill:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Open a pull request

For bug reports and feature requests, use GitHub Issues.

☕ Support

If immich-photo-manager saved you time or made your photo library easier to manage, consider buying me a coffee — it keeps the next one coming!

📜 License

MIT License — free to use, modify, and distribute.

Forged by Drolosoft · Tools we wish existed