apple-photos-mcp

Overview Schema Source Related Servers Discussions Admin

remove-from-album

Remove photo UUIDs from an album without deleting them from the library. Rebuilds the album with remaining photos and returns the updated album details.

Instructions

Use when: you want to take photos OUT of an album — undoing a mis-filing, or clearing reviewed items from a quarantine album. This removes ALBUM MEMBERSHIP only. Returns: the album AFTER the operation ({uuid, name, path} — note the uuid CHANGES when anything was removed), removedCount, removed, notInAlbum (requested UUIDs that weren't members — no-ops), albumRecreated, and previousAlbumUuid. Do not use when: you want to delete photos from the library — this server cannot delete photos at all (quarantine them in an album and review in Photos.app instead); or the photos aren't in the album (harmless, but pointless). Safety: WRITE tool — disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). NEVER deletes photos from the library — removed photos stay in All Photos and every other album. Photos' AppleScript has no remove-from-album verb, so the album is REBUILT (same name and remaining photos): its UUID changes and any custom manual sort order is lost; re-fetch the album UUID from the response. When none of the UUIDs are members, nothing is rebuilt. The replacement is built under a scratch name apple-photos-mcp-tmp-<hex> and renamed last, so a call killed mid-rebuild (e.g. the 10-minute budget expiring while copying a very large album) leaves the original album and every photo intact but can strand an apple-photos-mcp-tmp-… album to delete in Photos.app; each interrupted run strands a distinct one. Max 100 UUIDs per call. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`uuid`	Yes	Photo UUID(s) to remove from the album (1–100)
`album`	Yes	Album name or UUID (UUID-looking values try the id lookup first)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`album`	No
`removed`	No
`notInAlbum`	No
`removedCount`	No
`albumRecreated`	No
`previousAlbumUuid`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.1.13Sep 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv2.1.9Aug 7, 2026
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
Addedv2.0.0Jul 10, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the WRITE nature, the APPLE_PHOTOS_MCP_ENABLE_WRITES requirement, the never-deletes-photos guarantee, the album rebuild behavior (UUID change, lost sort order), the scratch-name mechanism, mid-rebuild failure effects, and the max 100 UUIDs. It also notes the macOS Automation permission and AppleScript drive. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the primary use case, followed by returns, exclusions, and safety details. It is organized into labeled sections and every sentence adds value, justifying its length given the tool's complexity. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (write operation, side effects, environment requirements, failure modes) and the presence of an output schema, the description covers all essential aspects: return values, side effects, edge cases (no-op UUIDs, interrupted runs), prerequisites, and limitations. An agent has everything needed to call it correctly and safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters already have detailed descriptions (album accepts name or UUID with id-lookup behavior; uuid array limited to 1–100). The tool description adds no new parameter meaning beyond reinforcing the max and the album lookup, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('take photos OUT of an album'), the exact resource (album membership), and the intent (undoing mis-filing, clearing quarantine). It explicitly differentiates from sibling tools like add-to-album and clarifies it does NOT delete photos, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use when' and 'Do not use when' sections, naming alternatives (quarantine in album, review in Photos.app) and conditions (photos not in album, deletion intent). This leaves no ambiguity about when to call this tool versus others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.