set-keywords
Add or remove keywords on a photo while preserving existing tags. Provides before/after lists and shows only actual changes.
Instructions
Use when: you want to add and/or remove keywords (tags) on a photo — tagging workflows, fixing a mis-tag — without disturbing its other keywords. Returns: uuid, before/after keyword lists (revert by re-running with the diff inverted), added and removed (what actually changed — adding an existing keyword or removing an absent one is a no-op), and changed. Do not use when: you want to browse keywords — use list-keywords; or find photos by keyword — use query. A keyword passed in both add and remove is rejected. Safety: WRITE tool — disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). UNION semantics — the photo's current keywords are read first and edits are merged in, so existing keywords you don't mention are ALWAYS preserved (never a blind replace). Metadata only — the image asset is untouched; the target photo is validated to exist first. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"uuid": "<uuid>"
},
"name": "set-keywords"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Keywords to add (created in Photos if new) | |
| uuid | Yes | Photo UUID (hex-with-dashes, as returned by query) | |
| remove | No | Keywords to remove from this photo (exact match) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | No | ||
| added | No | ||
| after | No | ||
| before | No | ||
| changed | No | ||
| removed | No |