rotate-photos

Rotate Photos

Connection Required — ALWAYS CHECK FIRST

Before doing ANYTHING else in this skill, call ping on the Immich MCP server.

• If ping succeeds → proceed with the skill normally.
• If ping fails or the MCP tools are not available → STOP. Do not continue. Tell the user:

Immich is not connected. This plugin needs a running Immich MCP server to work.

Run /setup-immich-photo-manager to configure your Immich connection.

Do NOT skip this check. Do NOT try to run any other tool first. Always ping, always block if it fails.

How It Works

Rotation uses Immich's non-destructive edits API. The original file is never modified. Immich stores the rotation as a display transform that is applied when serving thumbnails and previews.

Key Architecture Details

Concept	Detail
API endpoint	PUT /assets/{id}/edits
Storage	Server-side, persists in Immich database forever
Original file	Never touched
Thumbnails	Served rotated via ?edited=true query parameter
Accumulation	Each PUT replaces all edits — the tool must read current angle and add
Full circle	360° → edits are deleted entirely (isEdited returns to false)

MCP Tools

Tool	Purpose
rotate_assets	Rotate by album_id or asset_ids. Accumulates with existing rotation.
revert_asset_edits	Remove all edits (rotation, crop, mirror) — back to original.

Recommended User Workflow

1. In Immich web UI: Browse library, spot wrongly-rotated photos
2. Multi-select the rotated photos and add them to an album (e.g., "Fix Rotation")
3. Use this skill: rotate_assets(album_id="...", angle=90)
4. Verify in the Immich web UI — photos should appear rotated
5. If wrong direction: call again (rotation accumulates) or revert_asset_edits(album_id="...")
6. Clean up: Delete the temporary album when done (photos are not affected)

Rotation Angles

Angle	Direction	Use when
90	Clockwise	Photo tilted left
180	Upside down	Photo inverted
270	Counter-clockwise	Photo tilted right

Calling rotate_assets multiple times accumulates:

Current	+ angle	Result
0°	+90°	90°
90°	+90°	180°
180°	+90°	270°
270°	+90°	0° (edits removed, back to original)

Examples

Rotate an entire album 90° clockwise

rotate_assets(album_id="uuid-of-album", angle=90)

Rotate specific photos 270° (counter-clockwise)

rotate_assets(asset_ids=["uuid-1", "uuid-2", "uuid-3"], angle=270)

Undo all rotation on an album

revert_asset_edits(album_id="uuid-of-album")

Check current rotation state of an asset

Use get_asset_info(asset_id) and check:

• isEdited — true if any edits exist
• width / height — swapped if rotated 90° or 270°

For the exact angle, the tool reads GET /assets/{id}/edits internally.

Showing Results to the User

When generating HTML galleries or visual reports, thumbnails must be fetched with ?edited=true to reflect rotation. The MCP thumbnail tools (get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch) do this by default.

Limitations

• No auto-detection: There is no reliable way to automatically find wrongly-rotated photos. The user must identify them visually and add them to an album.
• CLIP search doesn't help: Searching for "sideways photo" returns semantically similar images, not actually misrotated ones.
• EXIF orientation: Immich already handles EXIF orientation tags when generating thumbnails. Photos that appear wrong in the UI have a genuine orientation problem that needs manual correction.
• Angle must be a multiple of 90: Arbitrary angles are not supported.

Common Mistakes

Mistake	Fix
Calling rotate_assets twice expecting it to stack without the accumulation fix	The tool handles this — it reads current angle and adds. No action needed.
Trying to detect rotated photos with CLIP search	Don't. Have the user identify them visually and create an album.
Applying CSS rotation to thumbnails instead of using ?edited=true	Always use the real edited thumbnail from the API. Never fake it with CSS.
Forgetting that edits are per-asset, not per-album	A photo rotated in Album A will also appear rotated in Album B.