import-photos
Import image and video files from disk into the Photos library, optionally into an existing album. Duplicate detection prevents re-imports.
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
| Name | Required | Description | Default |
|---|---|---|---|
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| album | No | ||
| imported | No | ||
| importedCount | No | ||
| requestedCount | No |