apple-photos-mcp

Overview Schema Source Related Servers Discussions Admin

export

Copy Apple Photos images to a destination folder by UUID, including original, edited, live, or raw versions.

Instructions

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. Returns: 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). Do not use when: you only need metadata or file paths rather than copies on disk — use get-photo; or you're still figuring out which photos to export — use query first. Safety: the only side-effecting tool on the read path — 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 — this is slow for large batches and requires Photos.app installed, signed in to iCloud, and Automation permission granted.

Input Schema

TableJSON Schema

Name	Required	Description
`raw`	No	Also export the raw image
`dest`	Yes	Destination directory (created if missing). Must be under the home directory, /tmp, /private/tmp, or /Volumes
`live`	No	Also export the live-photo video
`uuid`	Yes	Photo UUID(s) to export
`edited`	No	Export the edited version instead of the original
`library`	No	Path to a .photoslibrary (default: system Photos library)
`overwrite`	No	Overwrite existing files at the destination

Output Schema

TableJSON Schema

Name	Required	Description	Default
`skipped`	No
`exported`	No
`destination`	No
`skippedCount`	No
`exportedCount`	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
```

Changed2 schema fields changedv1.4.0Jul 9, 2026

changedInput schema / properties / dest / description

Previous value: -"Destination directory (created if missing)"New value: +"Destination directory (created if missing). Must be under the home directory, /tmp, /private/tmp, or /Volumes"

addedInput schema / properties / dest / minLength
```
Added value: +1
```

Changed4 schema fields changedv1.1.3Jun 30, 2026
- addedInput schema / properties / dest / maxLength
```
Added value: +4096
```
- addedInput schema / properties / library / maxLength
```
Added value: +4096
```
- addedInput schema / properties / uuid / items / maxLength
```
Added value: +256
```
- addedInput schema / properties / uuid / maxItems
```
Added value: +1000
```

Changed1 schema field changedv1.1.0Jun 23, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "destination": {
+      "type": "string"
+    },
+    "exported": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "exportedCount": {
+      "type": "number"
+    },
+    "skipped": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "skippedCount": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

First observedv0.1.4May 26, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly: it reveals file writes, directory creation, overwrite semantics, skip behavior, iCloud fallback via AppleScript, performance implications, and return shape. This is exemplary transparency for a side-effecting tool.

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 long but every sentence earns its place. It is structured with clear labels ('Use when', 'Do not use when', 'Returns', 'Safety') and front-loads the primary use case before diving into edge cases. This is appropriate density for a high-complexity tool.

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?

For a 7-parameter, side-effecting tool with no annotations, the description covers all needed operational context: parameters, destination constraints, overwrite behavior, skip reasons, return values, progress notifications, iCloud fallback, and permissions. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful behavior beyond the schema: it explains that edited/live/raw modify the default original export, that overwrite=true overwrites in place, and that dest must resolve to an allowed root. Only the library parameter is not elaborated, but its schema description is already sufficient.

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 clearly states the action: copying one or more photos by UUID to a destination directory on disk. It distinguishes itself from siblings by explicitly routing metadata-only needs to get-photo and exploration needs to query, so an agent can pick the right tool without opening schemas.

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?

The description includes explicit 'Use when' and 'Do not use when' guidance, names the exact alternatives (get-photo, query), and covers edge conditions like iCloud downloads requiring Photos.app and Automation permission. This leaves little to inference about when the tool should be invoked.

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