apple-photos-mcp 2.1.4 → 2.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -15
- package/build/index.js +30 -22
- package/docs/FULL-DISK-ACCESS.md +16 -7
- package/docs/LIMITATIONS.md +15 -5
- package/docs/WRITE-BACKEND.md +3 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -81,9 +81,24 @@ The Codex plugin runs the published `apple-photos-mcp` server through `npx` and
|
|
|
81
81
|
|
|
82
82
|
### Other Hosts (Hermes, Antigravity)
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
Two more hosts can run the same `apple-photos` MCP server (`npx -y apple-photos-mcp`). As a Python-sidecar (osxphotos) server it also needs Full Disk Access; see [Requirements](#requirements).
|
|
85
85
|
|
|
86
|
-
- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in
|
|
86
|
+
- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
hermes mcp add apple-photos --command npx --args -y apple-photos-mcp
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Or add it to `~/.hermes/config.yaml` by hand:
|
|
93
|
+
|
|
94
|
+
```yaml
|
|
95
|
+
mcp_servers:
|
|
96
|
+
apple-photos:
|
|
97
|
+
command: npx
|
|
98
|
+
args: ["-y", "apple-photos-mcp"]
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Restart your Hermes session afterward so the tools load.
|
|
87
102
|
- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-photos-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
|
|
88
103
|
|
|
89
104
|
### Manual Installation
|
|
@@ -217,7 +232,7 @@ The write tools stay **registered** even while disabled (MCP clients cache the t
|
|
|
217
232
|
- **Explicit targets only.** Every write takes explicit UUIDs, names, or file paths — there are no wildcard/all-photos operations, and every target is validated to exist before anything is modified (unknown UUIDs come back as clear errors or per-UUID `notFound` lists; import source paths must exist under the same allowlist roots as export).
|
|
218
233
|
- **Bounded batches.** Album operations accept at most 100 UUIDs per call; imports at most 50 files.
|
|
219
234
|
- **Reversible by design.** Metadata writes echo before/after values so an agent can revert; `set-keywords` uses union semantics (read-merge-write) so keywords you don't mention are never clobbered; album adds are idempotent; `set-photo-date` is a **dry run by default** — it writes nothing until you pass `dryRun: false`, and always echoes before/after so an applied change can be reverted.
|
|
220
|
-
- **The mechanism:** writes drive **Photos.app via AppleScript** (the [photoscript](https://github.com/RhetTbull/photoscript) library). Photos is launched if it isn't running, and macOS asks for **Automation permission** for the host app with a one-time system prompt on the first write. Writes always target the library **currently open in Photos.app** (normally the system library) — the `library` parameter of the read tools does not apply. (Reads, by contrast, go through osxphotos straight to the Photos database — fast and prompt-free. Why writes *can't* use that same path — and why osxphotos/PhotoKit aren't an escape from AppleScript — is spelled out in [docs/WRITE-BACKEND.md](docs/WRITE-BACKEND.md).)
|
|
235
|
+
- **The mechanism:** writes drive **Photos.app via AppleScript** (the [photoscript](https://github.com/RhetTbull/photoscript) library). Photos is launched if it isn't running, and macOS asks for **Automation permission** for the host app with a one-time system prompt on the first write. Writes always target the library **currently open in Photos.app** (normally the system library) — the `library` parameter of the read tools does not apply. (Reads, by contrast, go through osxphotos straight to the Photos database — fast and prompt-free. Why writes *can't* use that same path — and why osxphotos/PhotoKit aren't an escape from AppleScript — is spelled out in [docs/WRITE-BACKEND.md](https://github.com/sweetrb/apple-photos-mcp/blob/main/docs/WRITE-BACKEND.md).)
|
|
221
236
|
- **One quirk to know:** Photos' AppleScript dictionary has no "remove from album" verb, so `remove-from-album` **rebuilds the album** (same name, remaining photos): the album's UUID changes (the response reports old and new) and any custom manual sort order is lost.
|
|
222
237
|
|
|
223
238
|
---
|
|
@@ -240,7 +255,7 @@ Verify osxphotos is installed and the Photos library can be opened.
|
|
|
240
255
|
|
|
241
256
|
#### `doctor`
|
|
242
257
|
|
|
243
|
-
Run a full setup diagnostic: the resolved Python interpreter (path + version — warns when it's older than the required 3.11, with `brew install python@3.12` advice), osxphotos installation, Photos library readability, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or "unable to open" error.
|
|
258
|
+
Run a full setup diagnostic — six checks: the resolved Python interpreter (path + version — warns when it's older than the required 3.11, with `brew install python@3.12` advice), osxphotos installation, sidecar mode (persistent vs one-shot fallback, plus the last respawn), the write-tools gate (enabled/disabled, with the opt-in recipe and — when enabled — whether the photoscript backend and Photos.app look usable), Photos library readability, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or "unable to open" error.
|
|
244
259
|
|
|
245
260
|
**Parameters:** None
|
|
246
261
|
|
|
@@ -427,7 +442,7 @@ Return one photo as an **inline viewable image** — an MCP image content block
|
|
|
427
442
|
| `minSize` | number | No | Smallest acceptable long-edge size in pixels (default `360`, max `8192`). The smallest qualifying derivative is served — raise it (e.g. `1024`) when you need detail like small text |
|
|
428
443
|
| `library` | string | No | Path to a non-default `.photoslibrary` |
|
|
429
444
|
|
|
430
|
-
**Returns:** An image content block plus structured metadata: `uuid`, source `path`, `width`/`height`, `mimeType`, `byteSize`, and `isDerivative` (`false` means no suitable derivative existed and the image was rendered from the original via `sips` — never upscaled). Movies get a thumbnail only when Photos generated a poster-frame derivative; an iCloud-only photo with no local derivative or original returns an error suggesting `export` (which downloads on demand).
|
|
445
|
+
**Returns:** An image content block plus structured metadata: `uuid`, source `path`, `width`/`height`, `mimeType`, `byteSize`, and `isDerivative` (`false` means no suitable derivative existed and the image was rendered from the original via `sips` — never upscaled). Movies get a thumbnail only when Photos generated a poster-frame derivative; an iCloud-only photo with no local derivative or original returns an error suggesting `export` (which downloads on demand). Responses are capped at **8 MB**: derivative selection pre-filters on that cap, but a `sips`-rendered fallback from a very high-resolution original can still exceed it and returns `thumbnail is <n> bytes (cap 8388608); request a smaller minSize` — lower `minSize`, or use `export` for the full file.
|
|
431
446
|
|
|
432
447
|
---
|
|
433
448
|
|
|
@@ -437,12 +452,12 @@ Group **exact duplicates** using Photos' own fingerprint-based detection — the
|
|
|
437
452
|
|
|
438
453
|
| Parameter | Type | Required | Description |
|
|
439
454
|
|-----------|------|----------|-------------|
|
|
440
|
-
| `limit` | number | No | Max duplicate groups to return (default `100`; `groupCount` reports the total) |
|
|
455
|
+
| `limit` | number | No | Max duplicate groups to return (default `100`, max `10000`; `groupCount` reports the total) |
|
|
441
456
|
| `library` | string | No | Path to a non-default `.photoslibrary` |
|
|
442
457
|
|
|
443
458
|
**Returns:** `groupCount` (total groups), `returned`, and `groups` ordered newest-first — each with the member `uuids` and per-member `filename`, `date`, `size`, `width`/`height`, and `isMovie`. Hidden and Recently-Deleted photos are never group members.
|
|
444
459
|
|
|
445
|
-
**Exact means exact:** the fingerprint matches identical image data only — edited copies, resized versions, and burst siblings will NOT group. Use `get-thumbnail` on a group's members to eyeball them before acting. This server cannot delete photos (Photos exposes no scriptable delete) — to act on duplicates,
|
|
460
|
+
**Exact means exact:** the fingerprint matches identical image data only — edited copies, resized versions, and burst siblings will NOT group. Use `get-thumbnail` on a group's members to eyeball them before acting. This server cannot delete photos (Photos exposes no scriptable delete) — to act on duplicates, quarantine the extra copies into an album (`create-album` + `add-to-album` when [writes are enabled](#write-tools-opt-in), otherwise by hand in Photos.app) and review/delete inside Photos.app. See the [dedupe pattern](#duplicate-cleanup).
|
|
446
461
|
|
|
447
462
|
---
|
|
448
463
|
|
|
@@ -478,7 +493,7 @@ List keywords sorted by usage count.
|
|
|
478
493
|
|
|
479
494
|
| Parameter | Type | Required | Description |
|
|
480
495
|
|-----------|------|----------|-------------|
|
|
481
|
-
| `limit` | number | No | Cap to top-N keywords |
|
|
496
|
+
| `limit` | number | No | Cap to top-N keywords (max `100000`) |
|
|
482
497
|
| `library` | string | No | Path to a non-default `.photoslibrary` |
|
|
483
498
|
|
|
484
499
|
**Returns:** Keywords with their photo counts, sorted descending.
|
|
@@ -491,7 +506,7 @@ List people detected by Photos face recognition, sorted by photo count.
|
|
|
491
506
|
|
|
492
507
|
| Parameter | Type | Required | Description |
|
|
493
508
|
|-----------|------|----------|-------------|
|
|
494
|
-
| `limit` | number | No | Cap to top-N persons |
|
|
509
|
+
| `limit` | number | No | Cap to top-N persons (max `100000`) |
|
|
495
510
|
| `library` | string | No | Path to a non-default `.photoslibrary` |
|
|
496
511
|
|
|
497
512
|
**Returns:** Persons with their photo counts, sorted descending. Unidentified faces appear as `_UNKNOWN_`.
|
|
@@ -546,7 +561,7 @@ Export one or more photos by UUID to a destination directory.
|
|
|
546
561
|
|
|
547
562
|
### Write (opt-in — see [Write tools](#write-tools-opt-in))
|
|
548
563
|
|
|
549
|
-
All
|
|
564
|
+
All seven tools below require `APPLE_PHOTOS_MCP_ENABLE_WRITES=1` and return a clear opt-in error otherwise. They drive Photos.app via AppleScript (macOS Automation permission; Photos is launched if needed), always target the library currently open in Photos.app (no `library` parameter), and can never delete photos.
|
|
550
565
|
|
|
551
566
|
#### `create-album`
|
|
552
567
|
|
|
@@ -583,6 +598,8 @@ Remove photos from an album — **never from the library** (they remain in All P
|
|
|
583
598
|
|
|
584
599
|
**Album rebuild caveat:** Photos' AppleScript has no remove verb, so removal rebuilds the album (create replacement → copy the kept photos → delete the original → rename). The album's **UUID changes** (use `album.uuid` from the response) and custom manual sort order is lost. When none of the UUIDs are members, nothing is rebuilt (`albumRecreated: false`).
|
|
585
600
|
|
|
601
|
+
**If a rebuild is interrupted:** the replacement is built under a scratch name `apple-photos-mcp-tmp-<hex>` and renamed last. If the call is killed mid-rebuild — e.g. the 10-minute rebuild budget expires while copying a very large album — the original album and every photo are safe, but an `apple-photos-mcp-tmp-…` album may be left behind; delete it in Photos.app. In the rare case the kill lands in the brief window *after* the original was deleted, the kept photos are still safe under that scratch name — rename it back. The scratch name is picked fresh (and collision-checked) per call, so repeatedly retrying a timing-out removal strands a *distinct* album each time.
|
|
602
|
+
|
|
586
603
|
#### `set-photo-metadata`
|
|
587
604
|
|
|
588
605
|
Set a photo's title, description, and/or favorite flag. Only the fields you pass are touched.
|
|
@@ -590,8 +607,8 @@ Set a photo's title, description, and/or favorite flag. Only the fields you pass
|
|
|
590
607
|
| Parameter | Type | Required | Description |
|
|
591
608
|
|-----------|------|----------|-------------|
|
|
592
609
|
| `uuid` | string | Yes | Photo UUID |
|
|
593
|
-
| `title` | string | No | New title (empty string clears it) |
|
|
594
|
-
| `description` | string | No | New description (empty string clears it) |
|
|
610
|
+
| `title` | string | No | New title (≤ 255 chars; empty string clears it) |
|
|
611
|
+
| `description` | string | No | New description (≤ 2048 chars; empty string clears it) |
|
|
595
612
|
| `favorite` | boolean | No | Set or clear the favorite flag |
|
|
596
613
|
|
|
597
614
|
**Returns:** `uuid`, `updated` (which fields were written), and full `before` / `after` values of all three fields — revert a change by writing the `before` values back.
|
|
@@ -603,8 +620,8 @@ Add and/or remove keywords on a photo with **union semantics**: the photo's curr
|
|
|
603
620
|
| Parameter | Type | Required | Description |
|
|
604
621
|
|-----------|------|----------|-------------|
|
|
605
622
|
| `uuid` | string | Yes | Photo UUID |
|
|
606
|
-
| `add` | string[] | No | Keywords to add (≤ 100; created in Photos if new) |
|
|
607
|
-
| `remove` | string[] | No | Keywords to remove from this photo (≤ 100; exact match) |
|
|
623
|
+
| `add` | string[] | No | Keywords to add (≤ 100 entries, each ≤ 255 chars; created in Photos if new) |
|
|
624
|
+
| `remove` | string[] | No | Keywords to remove from this photo (≤ 100 entries, each ≤ 255 chars; exact match) |
|
|
608
625
|
|
|
609
626
|
At least one of `add` / `remove` is required; a keyword in both is rejected.
|
|
610
627
|
|
|
@@ -874,7 +891,7 @@ All configuration is optional — the server works out of the box.
|
|
|
874
891
|
|----------|---------|-------------|
|
|
875
892
|
| `APPLE_PHOTOS_MCP_ENABLE_WRITES` | unset (**read-only**) | Set to `1` to enable the [write tools](#write-tools-opt-in) (`create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords`, `set-photo-date`, `import-photos`). Until then every write tool returns a clear opt-in error and the server cannot modify the library. Restart the server after changing it. |
|
|
876
893
|
| `APPLE_PHOTOS_MCP_MAX_BUFFER` | `104857600` (100 MB) | Max bytes captured from the Python sidecar's stdout. Raise it if a very large library/query is truncated; lower it to cap memory. |
|
|
877
|
-
| `APPLE_PHOTOS_MCP_TIMEOUT` | `60000` (60 s) | Default per-command timeout, in milliseconds, for the Python sidecar. The first (cold) call parses the whole Photos database, and on very large libraries (100k+ photos) that load alone can exceed 60 s — raise this if tools report "Operation timed out". `
|
|
894
|
+
| `APPLE_PHOTOS_MCP_TIMEOUT` | `60000` (60 s) | Default per-command timeout, in milliseconds, for the Python sidecar. The first (cold) call parses the whole Photos database, and on very large libraries (100k+ photos) that load alone can exceed 60 s — raise this if tools report "Operation timed out". **It sets only the DEFAULT budget** — it applies to `query`, `get-photo`, `get-photos`, `get-thumbnail`, `library-info`, `list-albums`, `list-folders`, `list-keywords`, `list-persons` and `health-check`, and is ignored by every tool that carries a fixed budget: `get-selected-photos` 2 min; `find-duplicates`, `create-album`, `add-to-album`, `set-photo-metadata`, `set-keywords` and `set-photo-date` 5 min; `remove-from-album` and `import-photos` 10 min; `export` 30 min. Those budgets are not configurable — a timeout on one of them says so instead of pointing here. |
|
|
878
895
|
| `APPLE_PHOTOS_MCP_PERSISTENT_SIDECAR` | unset (persistent mode on) | Set to `0` (or `false`) to disable the long-lived serve-mode sidecar and spawn a fresh Python process per call (pre-1.4.0 behavior). Every call then re-pays the full library parse — only useful for debugging. |
|
|
879
896
|
| `APPLE_PHOTOS_MCP_SIDECAR_IDLE_MS` | `300000` (5 min) | How long the persistent sidecar may sit idle before it's killed to free memory (a resident parsed library holds hundreds of MB for large libraries). The next call transparently respawns it, re-paying the one-time parse. `0` = never kill on idle. |
|
|
880
897
|
| `APPLE_PHOTOS_MCP_NO_AUTO_SETUP` | unset (auto-setup on) | Set to `1` (or any truthy value) to disable the automatic first-use venv bootstrap. With it on, you must run `pnpm run setup` (or `pip3 install osxphotos`) yourself. |
|
package/build/index.js
CHANGED
|
@@ -21826,7 +21826,7 @@ function findSystemPython() {
|
|
|
21826
21826
|
}
|
|
21827
21827
|
}
|
|
21828
21828
|
throw new Error(
|
|
21829
|
-
`Python 3 not found on PATH. Install Python 3.11+ (stock macOS ships 3.9 \u2014 brew install python@3.12), then retry.
|
|
21829
|
+
`Python 3 not found on PATH. Install Python 3.11+ (stock macOS ships 3.9 \u2014 brew install python@3.12), then retry. Run the doctor tool to diagnose, or see ${REQUIREMENTS_URL}.`
|
|
21830
21830
|
);
|
|
21831
21831
|
}
|
|
21832
21832
|
function resolvePython() {
|
|
@@ -21965,10 +21965,11 @@ function mapStructuredError(structured) {
|
|
|
21965
21965
|
}
|
|
21966
21966
|
return structured;
|
|
21967
21967
|
}
|
|
21968
|
-
function timeoutError(timeoutMs) {
|
|
21969
|
-
|
|
21968
|
+
function timeoutError(timeoutMs, envConfigurable) {
|
|
21969
|
+
const remedy = envConfigurable ? `Raise ${ENV_PREFIX}_TIMEOUT (ms) if the library needs longer to load.` : `This tool's timeout is fixed at ${timeoutMs}ms; ${ENV_PREFIX}_TIMEOUT does not apply to it.`;
|
|
21970
|
+
return `Operation timed out after ${timeoutMs}ms. Library may be very large. ${remedy}`;
|
|
21970
21971
|
}
|
|
21971
|
-
async function execReader(command, args, timeoutMs) {
|
|
21972
|
+
async function execReader(command, args, timeoutMs, envConfigurable = true) {
|
|
21972
21973
|
const python = resolvePython();
|
|
21973
21974
|
const scriptPath = getScriptPath();
|
|
21974
21975
|
const fullArgs = [scriptPath, command, ...args];
|
|
@@ -22004,7 +22005,7 @@ async function execReader(command, args, timeoutMs) {
|
|
|
22004
22005
|
}
|
|
22005
22006
|
const bufferExceeded = /maxBuffer.*exceeded/i.test(error2.message ?? "");
|
|
22006
22007
|
if (error2.killed === true && !bufferExceeded || error2.message?.includes("ETIMEDOUT") || error2.message?.includes("timed out")) {
|
|
22007
|
-
return { error: timeoutError(timeoutMs) };
|
|
22008
|
+
return { error: timeoutError(timeoutMs, envConfigurable) };
|
|
22008
22009
|
}
|
|
22009
22010
|
if (stderr) {
|
|
22010
22011
|
return { error: stderr };
|
|
@@ -22070,7 +22071,7 @@ function getSidecarInfo() {
|
|
|
22070
22071
|
}
|
|
22071
22072
|
return { mode: "persistent", ...base };
|
|
22072
22073
|
}
|
|
22073
|
-
async function executeSidecar(command, args, timeoutMs, onProgress) {
|
|
22074
|
+
async function executeSidecar(command, args, timeoutMs, envConfigurable, onProgress) {
|
|
22074
22075
|
if (persistentModeEnabled() && serveDisabledReason === null) {
|
|
22075
22076
|
const outcome = await persistentClient.request(command, args, timeoutMs, onProgress);
|
|
22076
22077
|
switch (outcome.kind) {
|
|
@@ -22089,7 +22090,7 @@ async function executeSidecar(command, args, timeoutMs, onProgress) {
|
|
|
22089
22090
|
case "error":
|
|
22090
22091
|
return { error: mapStructuredError(outcome.error) };
|
|
22091
22092
|
case "timeout":
|
|
22092
|
-
return { error: timeoutError(timeoutMs) };
|
|
22093
|
+
return { error: timeoutError(timeoutMs, envConfigurable) };
|
|
22093
22094
|
case "fallback": {
|
|
22094
22095
|
if (!looksLikeMissingDep(outcome.reason)) {
|
|
22095
22096
|
serveDisabledReason = outcome.reason;
|
|
@@ -22104,17 +22105,18 @@ async function executeSidecar(command, args, timeoutMs, onProgress) {
|
|
|
22104
22105
|
}
|
|
22105
22106
|
}
|
|
22106
22107
|
}
|
|
22107
|
-
return execReader(command, args, timeoutMs);
|
|
22108
|
+
return execReader(command, args, timeoutMs, envConfigurable);
|
|
22108
22109
|
}
|
|
22109
22110
|
async function runPhotosReader(command, args, timeoutMs, onProgress) {
|
|
22110
22111
|
return sidecarGate(async () => {
|
|
22111
22112
|
await ensureReady();
|
|
22113
|
+
const envConfigurable = timeoutMs === void 0;
|
|
22112
22114
|
const timeout = timeoutMs ?? getDefaultTimeout();
|
|
22113
|
-
const result = await executeSidecar(command, args, timeout, onProgress);
|
|
22115
|
+
const result = await executeSidecar(command, args, timeout, envConfigurable, onProgress);
|
|
22114
22116
|
if (result.error && looksLikeMissingDep(result.error) && !bootstrapAttempted && !autoSetupDisabled()) {
|
|
22115
22117
|
if (await attemptBootstrap()) {
|
|
22116
22118
|
persistentClient.kill("venv bootstrapped");
|
|
22117
|
-
return executeSidecar(command, args, timeout, onProgress);
|
|
22119
|
+
return executeSidecar(command, args, timeout, envConfigurable, onProgress);
|
|
22118
22120
|
}
|
|
22119
22121
|
}
|
|
22120
22122
|
return result;
|
|
@@ -23494,7 +23496,7 @@ ${lines.join("\n")}`, { count, persons });
|
|
|
23494
23496
|
server.registerTool(
|
|
23495
23497
|
"export",
|
|
23496
23498
|
{
|
|
23497
|
-
description: "Use when: you want to copy one or more photos (by UUID, typically from query) out to a destination directory on disk. By default exports the original; set edited=true for the edited version, live=true to also include the live-photo video, raw=true to also include the raw image. Large batches report per-photo MCP progress notifications when the request carries a progressToken.\nReturns: the destination path, counts of files exported and skipped, the exported file paths, and a per-UUID reason for anything skipped (e.g. file already exists at the destination, UUID not found / in trash, iCloud download failed).\nDo not use when: you only need metadata or file paths rather than copies on disk \u2014 use get-photo; or you're still figuring out which photos to export \u2014 use query first.\nSafety:
|
|
23499
|
+
description: "Use when: you want to copy one or more photos (by UUID, typically from query) out to a destination directory on disk. By default exports the original; set edited=true for the edited version, live=true to also include the live-photo video, raw=true to also include the raw image. Large batches report per-photo MCP progress notifications when the request carries a progressToken.\nReturns: the destination path, counts of files exported and skipped, the exported file paths, and a per-UUID reason for anything skipped (e.g. file already exists at the destination, UUID not found / in trash, iCloud download failed).\nDo not use when: you only need metadata or file paths rather than copies on disk \u2014 use get-photo; or you're still figuring out which photos to export \u2014 use query first.\nSafety: the only side-effecting tool on the read path \u2014 it writes files into the destination directory (created if missing); the opt-in write tools (APPLE_PHOTOS_MCP_ENABLE_WRITES=1) can also modify the library, but nothing else here writes anywhere. dest must resolve (after expanding ~ and following symlinks) to a path under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected. With overwrite=true it OVERWRITES existing files of the same name in place; without it, existing files are skipped and reported per-UUID. If an original isn't on disk (iCloud 'Optimize Mac Storage'), the export falls back to driving Photos.app via AppleScript to download it on demand \u2014 this is slow for large batches and requires Photos.app installed, signed in to iCloud, and Automation permission granted.",
|
|
23498
23500
|
inputSchema: {
|
|
23499
23501
|
...libraryArg,
|
|
23500
23502
|
uuid: external_exports.array(external_exports.string().max(256)).min(1).max(1e3).describe("Photo UUID(s) to export"),
|
|
@@ -23516,17 +23518,20 @@ server.registerTool(
|
|
|
23516
23518
|
},
|
|
23517
23519
|
withErrorHandling(async ({ library, uuid: uuid2, dest, edited, live, raw, overwrite }, extra) => {
|
|
23518
23520
|
const progressToken = extra?._meta?.progressToken;
|
|
23521
|
+
const inFlight = [];
|
|
23519
23522
|
const onProgress = progressToken === void 0 ? void 0 : (p) => {
|
|
23520
|
-
|
|
23521
|
-
|
|
23522
|
-
|
|
23523
|
-
|
|
23524
|
-
|
|
23525
|
-
|
|
23526
|
-
|
|
23527
|
-
|
|
23528
|
-
|
|
23529
|
-
|
|
23523
|
+
inFlight.push(
|
|
23524
|
+
extra.sendNotification({
|
|
23525
|
+
method: "notifications/progress",
|
|
23526
|
+
params: {
|
|
23527
|
+
progressToken,
|
|
23528
|
+
progress: p.done,
|
|
23529
|
+
total: p.total,
|
|
23530
|
+
message: p.current ? `Exporting ${p.current} (${p.done + 1}/${p.total})` : `Exported ${p.done}/${p.total}`
|
|
23531
|
+
}
|
|
23532
|
+
}).catch(() => {
|
|
23533
|
+
})
|
|
23534
|
+
);
|
|
23530
23535
|
};
|
|
23531
23536
|
const result = await manager.exportPhotos(uuid2, dest, {
|
|
23532
23537
|
edited,
|
|
@@ -23536,6 +23541,9 @@ server.registerTool(
|
|
|
23536
23541
|
library,
|
|
23537
23542
|
onProgress
|
|
23538
23543
|
});
|
|
23544
|
+
if (inFlight.length) {
|
|
23545
|
+
await Promise.all(inFlight);
|
|
23546
|
+
}
|
|
23539
23547
|
const lines = [
|
|
23540
23548
|
`Destination: ${result.destination}`,
|
|
23541
23549
|
`Exported: ${result.exportedCount} file(s)`,
|
|
@@ -23614,7 +23622,7 @@ server.registerTool(
|
|
|
23614
23622
|
server.registerTool(
|
|
23615
23623
|
"remove-from-album",
|
|
23616
23624
|
{
|
|
23617
|
-
description: "Use when: you want to take photos OUT of an album \u2014 undoing a mis-filing, or clearing reviewed items from a quarantine album. This removes ALBUM MEMBERSHIP only.\nReturns: the album AFTER the operation ({uuid, name, path} \u2014 note the uuid CHANGES when anything was removed), removedCount, removed, notInAlbum (requested UUIDs that weren't members \u2014 no-ops), albumRecreated, and previousAlbumUuid.\nDo not use when: you want to delete photos from the library \u2014 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).\nSafety: WRITE tool \u2014 disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). NEVER deletes photos from the library \u2014 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. Max 100 UUIDs per call. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.",
|
|
23625
|
+
description: "Use when: you want to take photos OUT of an album \u2014 undoing a mis-filing, or clearing reviewed items from a quarantine album. This removes ALBUM MEMBERSHIP only.\nReturns: the album AFTER the operation ({uuid, name, path} \u2014 note the uuid CHANGES when anything was removed), removedCount, removed, notInAlbum (requested UUIDs that weren't members \u2014 no-ops), albumRecreated, and previousAlbumUuid.\nDo not use when: you want to delete photos from the library \u2014 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).\nSafety: WRITE tool \u2014 disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). NEVER deletes photos from the library \u2014 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-\u2026` 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.",
|
|
23618
23626
|
inputSchema: {
|
|
23619
23627
|
album: external_exports.string().min(1).max(1024).describe("Album name or UUID (UUID-looking values try the id lookup first)"),
|
|
23620
23628
|
uuid: external_exports.array(uuidSchema).min(1).max(100).describe("Photo UUID(s) to remove from the album (1\u2013100)")
|
package/docs/FULL-DISK-ACCESS.md
CHANGED
|
@@ -2,8 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
Apple Photos MCP needs **Full Disk Access (FDA)** for the process that runs the
|
|
4
4
|
MCP server. Unlike some Apple MCP servers, this is **not optional** — without it,
|
|
5
|
-
**no tool works
|
|
6
|
-
|
|
5
|
+
**no read tool works**: every read (`query`, browse, thumbnails, `export`,
|
|
6
|
+
diagnostics) goes through osxphotos to the Photos library's SQLite database, and
|
|
7
|
+
that database lives in a macOS-protected directory.
|
|
8
|
+
|
|
9
|
+
The opt-in **write** tools are the one exception to the *mechanism*: they drive
|
|
10
|
+
Photos.app over AppleScript rather than reading the database, so what they need
|
|
11
|
+
is macOS **Automation** permission, not FDA (a write failing with AppleScript
|
|
12
|
+
error `-1743` is an Automation problem — granting FDA will not fix it; see
|
|
13
|
+
[WRITE-BACKEND.md](./WRITE-BACKEND.md)). FDA is still effectively mandatory in
|
|
14
|
+
practice, because the photo UUIDs the write tools operate on come from
|
|
15
|
+
FDA-backed reads.
|
|
7
16
|
|
|
8
17
|
## Why it's needed
|
|
9
18
|
|
|
@@ -19,7 +28,7 @@ Everything under `~/Pictures/Photos Library.photoslibrary/` is gated by macOS
|
|
|
19
28
|
privacy protection. Reading it requires **Full Disk Access** for the *host*
|
|
20
29
|
process — the application that actually launches `node` and spawns the Python
|
|
21
30
|
sidecar. Without that grant, macOS denies the read before osxphotos can open the
|
|
22
|
-
database, and the
|
|
31
|
+
database, and the read path can do nothing.
|
|
23
32
|
|
|
24
33
|
(The MCP only ever **reads** the library database; it never writes to it. See
|
|
25
34
|
[LIMITATIONS.md](./LIMITATIONS.md).)
|
|
@@ -48,10 +57,10 @@ database, and the server can do nothing.
|
|
|
48
57
|
## Verifying it worked
|
|
49
58
|
|
|
50
59
|
The best verification is the **`doctor`** tool. It runs the full setup
|
|
51
|
-
diagnostic —
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
60
|
+
diagnostic — six checks, including **Full Disk Access** — and reports each as
|
|
61
|
+
ok / warn / fail. The Full Disk Access check is explicit: if the grant took
|
|
62
|
+
effect it reports `ok`; if it's missing it reports `fail` with a pointer back to
|
|
63
|
+
this guide.
|
|
55
64
|
|
|
56
65
|
For a quicker smoke test, run **`health-check`**. It confirms two things in one
|
|
57
66
|
shot: that osxphotos is installed, and that the Photos library can actually be
|
package/docs/LIMITATIONS.md
CHANGED
|
@@ -52,7 +52,11 @@ so writes always target that library (normally the system one) — the read
|
|
|
52
52
|
tools' `library` parameter does not apply; (3) Photos' AppleScript dictionary
|
|
53
53
|
has **no remove-from-album verb**, so `remove-from-album` rebuilds the album
|
|
54
54
|
(same name, remaining photos): the album's **UUID changes** and custom manual
|
|
55
|
-
sort order is lost
|
|
55
|
+
sort order is lost — the replacement is built under a scratch name
|
|
56
|
+
`apple-photos-mcp-tmp-<hex>` and renamed last, so a rebuild killed part-way
|
|
57
|
+
(e.g. its fixed 10-minute budget expiring on a very large album) leaves the
|
|
58
|
+
original album and every photo safe but can strand an `apple-photos-mcp-tmp-…`
|
|
59
|
+
album, one per interrupted attempt; (4) Photos is launched if it isn't running, so the first
|
|
56
60
|
write can be slow; (5) `set-photo-date` rewrites the **Photos library date
|
|
57
61
|
only** — the same thing Photos.app's *Adjust Date & Time* does — the file's
|
|
58
62
|
EXIF is never modified, so an exported original still carries its old EXIF
|
|
@@ -62,8 +66,10 @@ duplicate makes Photos.app show a **blocking dialog** a human must answer.
|
|
|
62
66
|
**What to do:** Run `doctor` first — its `writes` check reports the gate state
|
|
63
67
|
and backend readiness. Grant the Automation prompt once from a GUI session.
|
|
64
68
|
After a `remove-from-album`, use the returned `album.uuid` (or the album name)
|
|
65
|
-
for follow-up calls
|
|
66
|
-
|
|
69
|
+
for follow-up calls; if one was interrupted, delete any leftover
|
|
70
|
+
`apple-photos-mcp-tmp-…` album in Photos.app (or, if the original vanished,
|
|
71
|
+
rename the scratch album back). Preview date fixes with `set-photo-date`'s
|
|
72
|
+
default dry run before applying.
|
|
67
73
|
|
|
68
74
|
## `get-selected-photos` needs a live GUI selection
|
|
69
75
|
|
|
@@ -106,7 +112,7 @@ its dedicated Full Disk Access check reports ok / warn / fail with remediation
|
|
|
106
112
|
**Why:** Opening a Photos library means starting Python, importing osxphotos,
|
|
107
113
|
and parsing the entire library database — about 4 seconds on a ~30k-photo
|
|
108
114
|
library, and it scales with library size (a 100k+ photo library can take much
|
|
109
|
-
longer, potentially past the default 60 s
|
|
115
|
+
longer, potentially past the default 60 s budget — raise
|
|
110
116
|
`APPLE_PHOTOS_MCP_TIMEOUT` if so). Since 1.4.0 the sidecar is a **persistent
|
|
111
117
|
process**, so this cost is paid **once**: the parsed library stays resident
|
|
112
118
|
and follow-up calls complete in milliseconds. The cold cost recurs only when
|
|
@@ -118,7 +124,11 @@ are never stale).
|
|
|
118
124
|
|
|
119
125
|
**What to do:** Nothing, usually — chain as many calls as you like; only the
|
|
120
126
|
first pays the parse. If even the cold call times out on a very large library,
|
|
121
|
-
raise `APPLE_PHOTOS_MCP_TIMEOUT` (ms)
|
|
127
|
+
raise `APPLE_PHOTOS_MCP_TIMEOUT` (ms) — but note it sets only the **default**
|
|
128
|
+
budget: `export` (30 min), `import-photos` and `remove-from-album` (10 min),
|
|
129
|
+
the other write tools and `find-duplicates` (5 min) and `get-selected-photos`
|
|
130
|
+
(2 min) carry their own fixed budgets that the variable cannot change, and a
|
|
131
|
+
timeout on one of those says so rather than pointing at the variable. To keep the sidecar resident longer (or
|
|
122
132
|
forever), raise `APPLE_PHOTOS_MCP_SIDECAR_IDLE_MS` or set it to `0` — at the
|
|
123
133
|
price of a few hundred MB of resident memory for large libraries. `doctor`'s
|
|
124
134
|
`sidecar_mode` check shows whether the persistent sidecar is active and when
|
package/docs/WRITE-BACKEND.md
CHANGED
|
@@ -10,7 +10,8 @@ ends, explained below.
|
|
|
10
10
|
| Path | Backend | Why |
|
|
11
11
|
|------|---------|-----|
|
|
12
12
|
| **Reads** — `query`, browse, `export`, diagnostics | **osxphotos**, reading the Photos SQLite DB directly | Fast, no app scripting, no Automation prompt, no Photos.app launch. |
|
|
13
|
-
| **Writes** — `create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords` (opt-in, gated behind `APPLE_PHOTOS_MCP_ENABLE_WRITES=1`) | **photoscript → AppleScript → Photos.app** | The only *safe, supported* way to mutate the live library. |
|
|
13
|
+
| **Writes** — `create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords`, `set-photo-date`, `import-photos` (opt-in, gated behind `APPLE_PHOTOS_MCP_ENABLE_WRITES=1`) | **photoscript → AppleScript → Photos.app** | The only *safe, supported* way to mutate the live library. |
|
|
14
|
+
| **`get-selected-photos`** — the one photoscript-backed READ (not gated) | **photoscript → AppleScript → Photos.app**, then osxphotos for the metadata | A live GUI selection exists only inside Photos.app; nothing in the database describes it. |
|
|
14
15
|
|
|
15
16
|
## Why not write to the SQLite DB the way we read it?
|
|
16
17
|
|
|
@@ -39,7 +40,7 @@ not grant PhotoKit write access to a bare `python3`/`node` interpreter. osxphoto
|
|
|
39
40
|
bundles a PhotoKit module, and its own source notes it *"[hasn't] figured out how
|
|
40
41
|
to get the call to requestAuthorization to actually work"* for this case.
|
|
41
42
|
Shipping PhotoKit writes would mean building, signing, notarizing, and
|
|
42
|
-
distributing a native (Swift) helper — a large lift, disproportionate to
|
|
43
|
+
distributing a native (Swift) helper — a large lift, disproportionate to seven
|
|
43
44
|
opt-in tools, and an unsolved problem even in osxphotos.
|
|
44
45
|
|
|
45
46
|
## The accepted trade-off
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "apple-photos-mcp",
|
|
3
|
-
"version": "2.1.
|
|
3
|
+
"version": "2.1.6",
|
|
4
4
|
"description": "MCP server for Apple Photos - query, search, export, and inspect the macOS Photos library via Claude and other AI assistants, plus opt-in album/metadata write tools (read-only by default)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "build/index.js",
|
|
@@ -87,7 +87,7 @@
|
|
|
87
87
|
"test:coverage": "vitest run --coverage",
|
|
88
88
|
"test:integration": "vitest run --config vitest.integration.config.ts",
|
|
89
89
|
"test:all": "vitest run && vitest run --config vitest.integration.config.ts",
|
|
90
|
-
"version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .
|
|
90
|
+
"version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .antigravity-plugin",
|
|
91
91
|
"preinstall": "node -e \"const fs=require('fs');const ua=process.env.npm_config_user_agent||'';if(fs.existsSync('.git')&&!ua.startsWith('pnpm')){console.error('\\nThis repo uses pnpm. npm/yarn resolve dependencies off-lockfile and the committed bundle will mismatch CI.\\n\\n corepack enable && pnpm install --frozen-lockfile\\n');process.exit(1)}\""
|
|
92
92
|
}
|
|
93
93
|
}
|