apple-photos-mcp

Overview Schema Source Related Servers Discussions Admin

import-photos

Import local image and video files into the Apple Photos library, optionally into an existing album. Validates paths, checks for duplicates, and reports imported items.

Instructions

Use when: you have image/video files on disk that belong in the Photos library — round-trip edits (export → fix → import), a folder of scans, an SD-card ingest — optionally filed straight into an existing album. Returns: requestedCount (validated source files), importedCount, imported (uuid + filename per new item — feed into get-photos / add-to-album / set-photo-date), and the album when one was targeted. importedCount < requestedCount usually means Photos skipped duplicates. Do not use when: the target album doesn't exist yet — call create-album first (a missing album is an error, not auto-created); or the files are outside your home directory, /tmp, /private/tmp, or /Volumes — those paths are rejected. Safety: WRITE tool — disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). Only ADDS to the library — never modifies or deletes anything; source files stay where they are (Photos copies them in). But note the reverse door is closed: Photos' AppleScript has no photo-delete verb, so an import cannot be programmatically undone — removing a mistaken import requires Photos.app by hand. Every path is validated (absolute, exists, allowed root) before anything imports. Duplicate checking is ON by default; a duplicate then makes Photos.app show a BLOCKING dialog a human must answer (the call waits up to its timeout) — set skipDuplicateCheck=true only when duplicates are acceptable, because they WILL be re-added silently. Drives Photos.app via AppleScript (requires macOS Automation permission; launches Photos if needed). Imports go into the library currently open in Photos.app.

Input Schema

TableJSON Schema

Name	Required	Description
`album`	No	EXISTING album (name or UUID) to file the imports into — create it with create-album first if needed
`paths`	Yes	Absolute (or ~-prefixed) file paths of images/videos to import (1–50). Must exist, under your home directory, /tmp, /private/tmp, or /Volumes
`skipDuplicateCheck`	No	true = skip Photos' duplicate check: duplicates WILL be re-imported silently. Default false: Photos checks, and a found duplicate raises a blocking dialog in Photos.app that a human must answer

Output Schema

TableJSON Schema

Name	Required	Description	Default
`album`	No
`imported`	No
`importedCount`	No
`requestedCount`	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.1.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 provided, the description carries the full behavioral burden and handles it thoroughly. It discloses the write-safety env var requirement, that imports only add and never modify/delete, that source files remain untouched, that imports cannot be undone programmatically, that duplicate checks can trigger blocking dialogs, and that AppleScript/Automation permissions are required.

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 each section earns its place for a write tool with significant safety caveats. It is structured by purpose, return values, exclusions, and safety, with critical constraints front-loaded in the 'Use when' and 'Do not use when' sections.

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 tool's complexity, zero annotations, and write-side effects, the description covers everything an agent needs: when to use it, what it returns, path validation, duplication behavior, permission requirements, error conditions, and undo limitations. The output schema exists, and the description still explains the meaning of the return counts and IDs.

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 description coverage is 100%, so the schema already documents all three parameters well. The description reinforces key constraints (existing album, allowed path roots, duplicate-check behavior), but it does not add substantial new semantics beyond what the schema's property descriptions already provide.

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 tool imports image/video files from disk into the Photos library, and distinguishes it from siblings by describing the return contract and what it does not do. The 'Use when' examples (round-trip edits, folder scans, SD-card ingest) make the purpose concrete and identifiable.

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 explicitly says when to use the tool and when not to, including the prerequisite that the target album must already exist and that create-album should be called first. It also gives path restrictions and duplicate-handling guidance, making the selection and invocation decision fully explicit.

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