apple-photos-mcp

Overview Schema Source Related Servers Discussions Admin

set-photo-date

Fix incorrect photo dates by setting an absolute date or shifting by seconds. Preview changes safely, then apply to the Photos library.

Instructions

Use when: a photo's date/time is wrong and you want to fix it — trailcam or scanner imports stamped with the upload time, a camera with a mis-set clock, scanned prints. Set an absolute date OR shift by a number of seconds (exactly one of date / shiftSeconds). DRY RUN BY DEFAULT: with dryRun omitted (or true) it only reports the current and would-be dates — preview first, then re-run with dryRun=false to write. Returns: uuid, before and after datetimes (on a dry run, after = the would-be date), shiftSeconds (the effective delta), applied, and dryRun. Revert an applied change by re-running with date= and dryRun=false. Do not use when: you want to find photos by date — use query; or you expect the file's EXIF to change — this edits the Photos library date only. Safety: WRITE tool — disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). Rewrites the photo's date in the Photos LIBRARY DATABASE only — the same operation as Photos.app's 'Adjust Date & Time'; the original file's EXIF is never modified. Dates are interpreted in the Mac's local timezone (a timezone-aware ISO datetime is converted to local). Nothing is written unless dryRun=false is passed explicitly, and before/after are always echoed so any change can be reverted. 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.

Input Schema

TableJSON Schema

Name	Required	Description
`date`	No	Absolute new date-time, ISO 8601 (e.g. 2026-05-14T06:32:00), interpreted in the Mac's local timezone unless a UTC offset is included. Exactly one of date / shiftSeconds
`uuid`	Yes	Photo UUID (hex-with-dashes, as returned by query)
`dryRun`	No	Default TRUE: preview the before/after dates without writing anything. Pass false to actually write the new date
`shiftSeconds`	No	Shift the current date by this many seconds (negative = earlier; e.g. -86400 = one day back). Exactly one of date / shiftSeconds

Output Schema

TableJSON Schema

Name	Required	Description	Default
`uuid`	No
`after`	No
`before`	No
`dryRun`	No
`applied`	No
`shiftSeconds`	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.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 and does so thoroughly: dry-run default, explicit write only when dryRun=false, library-database-only modification, no EXIF changes, timezone handling, validation, AppleScript permissions, and the required APPLE_PHOTOS_MCP_ENABLE_WRITES flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with labeled sections and front-loaded critical warnings. Minor redundancy exists between the 'DRY RUN BY DEFAULT' statement and the later safety note that nothing is written unless dryRun=false, but the length is justified given the tool's write risk and operational complexity.

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 complex write tool with no annotations, the description is exceptionally complete: preconditions, permissions, safety gating, exact behavior, return field explanation, revert path, timezone handling, and exclusions are all covered. An agent has everything needed to preview, write, and undo the operation.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds meaning beyond the schema: exactly one of date/shiftSeconds must be provided, dry runs return would-be dates, re-running with date=<echoed before> reverts, and shiftSeconds semantics are reinforced. It also clarifies timezone interpretation for the date parameter.

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 opens with a specific purpose: fixing a photo's date/time, with concrete examples of when this is needed. It clearly distinguishes this tool from query (finding by date) and from EXIF-modifying operations, so an agent can tell exactly what resource and operation are involved.

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?

It explicitly states 'Use when' and 'Do not use when', names the query tool as the alternative for date-based searching, and warns against expecting EXIF changes. It also mandates the exact selection between date and shiftSeconds, leaving no ambiguity about invocation intent.

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