Apple Photos MCP Server & CLI

A free, open source Apple Photos MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents search, look at and organize your library, on your Mac.

Star on GitHub

npm

by Navid Moazzez·Updated 30 de set. de 2026·9 min read

~/apple-photos-mcp-cli

$ claude

Claude Code v2.1.220

MCP CLI

Add it with a single command in a terminal.

claude mcp add apple-photos \
  -- npx -y @thenavidm/apple-photos-mcp-cli

2
In Claude Code, type /mcp. Apple Photos should show as connected.
```
/mcp
```

Mac only. Needs Node 20 or newer, uv, and Full Disk Access for the app that runs it. Turn it on.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Apple Photos MCP server and CLI gives your AI real access to your own Apple Photos library, on your Mac. It searches everything Apple already indexed, looks at the photos, organizes them into albums and exports originals.

It's one install with 2 ways in. Claude, Codex, Cursor or any other MCP app calls its 13 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

Here's what the Apple Photos MCP server and CLI is, how to set it up in each app, and every tool it has.

What is the Apple Photos MCP server & CLI?

The Apple Photos MCP server & CLI is a free, open source program that lets AI agents search and organize your own Apple Photos library for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to your library, right on your Mac.

The CLI is the same program as commands. apple-photos-cli library-stats runs the same code your AI runs when you ask how many photos you have, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Find my photo of that whiteboard from the Bogota trip.
Which receipts do I have from Vietnam?
Show me videos from Dubai in 2024.
How many photos do I have, and how many are just screenshots?
Add these 5 to an album called Best of Bali.
Export the original of that one to my Desktop.

The first one shows why this is useful. Apple already ran machine learning over every photo on your Mac, and this gives your AI that whole index, so it can search, cross-check and then look before it answers.

How to install the Apple Photos MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and there's no account or key to add.

Before you start0/3

You have a Mac with Photos.

You have Node 20 or newer on your Mac.

You have uv, which fetches the Python engine on first run.

Pro tip: If you don't have uv yet, curl -LsSf https://astral.sh/uv/install.sh | sh installs it. The engine is Python because the only libraries that can read a Photos library are Python.

Give it access to your library

There's no sign-in. Your Photos library is protected, so the only setup is one macOS permission, once.

Turn on Full Disk Access0/4

1Open System Settings, then Privacy & Security, then Full Disk Access.

2Click + and add the app that runs the server: Claude Desktop, Terminal or iTerm for Claude Code, or Cursor, VS Code or Windsurf.

3Make sure its toggle is on.

4Quit that app completely with Cmd+Q and open it again, because the permission is only read on a fresh start.

Skipping that last step is the most common reason it looks broken.

The first time a tool changes something, macOS asks if the app may control Photos. Click OK, or find it later under Privacy & Security, then Automation.

Check that it works

Run the doctor. It checks the permission, finds your library and counts what Apple indexed.

npx -y @thenavidm/apple-photos-mcp-cli doctor

A healthy result shows how many photos it indexed. "permission denied" means Full Disk Access, and remember the Cmd+Q.

Use the Apple Photos CLI

The CLI is the same 13 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so search_photos runs as apple-photos-cli search-photos.

npm install -g @thenavidm/apple-photos-mcp-cli
apple-photos-cli
apple-photos-cli library-stats
apple-photos-cli search-photos "sunset" --limit 5 --screenshots exclude

The bare apple-photos-cli lists every command, and apple-photos-cli <command> --help shows what a command takes. Archiving asks for a confirm first, like it does for your AI.

These flags work on every command:

Flag	What it does
`--json`	Prints JSON
`--compact`	Prints the JSON on one line
`--select a,b.c`	Keeps only those fields

A script can branch on the exit code:

Exit code	What it means
0	It worked
2	The command was typed wrong, or a write needed `--confirm`
3	A photo or album wasn't found
4	macOS refused access, so turn on Full Disk Access or allow Automation for Photos
5	The engine or Photos failed
10	The engine couldn't start, so install uv

MCP server or CLI: which one?

Both are the same program with the same 13 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool

MCP server: 3,800 tokens
CLI: Nothing

Every message, in Claude Code

MCP server: 660 tokens
CLI: Nothing

When Apple Photos comes up

MCP server: Nothing more, or in Claude Code the tools it picks
CLI: 2,500 tokens, once

20 messages with Apple Photos in 1, every tool loaded

MCP server: 77,000 tokens
CLI: 2,500 tokens

Works in Claude Desktop's chat

MCP server: Yes
CLI: No, there's no terminal there

Works in a script, a cron job or CI

MCP server: No
CLI: Yes

What it costs	MCP server	CLI
Every message, in an app that loads every tool	3,800 tokens	Nothing
Every message, in Claude Code	660 tokens	Nothing
When Apple Photos comes up	Nothing more, or in Claude Code the tools it picks	2,500 tokens, once
20 messages with Apple Photos in 1, every tool loaded	77,000 tokens	2,500 tokens
Works in Claude Desktop's chat	Yes	No, there's no terminal there
Works in a script, a cron job or CI	No	Yes

An app that loads every tool up front sends the full list with every message, whether you mention Apple Photos or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Apple Photos comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 180 tokens.

When the whole conversation is about Apple Photos, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using your photos, with your AI app's own switch. APPLE_PHOTOS_READ_ONLY=1 cuts it to the 7 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

What Apple Photos already knows

Apple indexed everything on your Mac: scene labels from a list of about 1,500 words, text it read inside each photo, the activity, the kind of place and the location. None of that needs the Photos app open to read.

Your own titles and keywords are almost certainly empty, so search for what a photo looks like, not what you called it. The word list is closed, so "golden hour" finds nothing while "Sunset" works, and list_vocabulary shows every word Apple knows.

Most of your photos live in iCloud, not on your Mac. Previews still work from Apple's cached thumbnails, and exporting an original downloads it first, which is why exporting is slow.

Faces only work for people you named in the People album.

Every Apple Photos tool

All 13 tools, grouped the way the repo groups them. 7 only read, and 6 change something in your library.

Search, look and organize

search_photos

What it does: Search the entire Photos library through Apple's own on-device index: what a picture looks like, text read inside it, the place, the activity, and any named faces.
Kind: Reads

look_at_photos

What it does: Return the images themselves so they can be looked at, rather than reasoned about from filenames and labels.
Kind: Reads

photo_info

What it does: Everything Photos knows about specific items: date, place, camera and lens, dimensions, albums, keywords, faces, and whether the original is on this Mac or still in iCloud.
Kind: Reads

library_stats

What it does: Real totals for the whole library in one call: items, photos against videos, favourites, screenshots, how many carry ML labels, text or a place, named people, and every album.
Kind: Reads

list_vocabulary

What it does: List the scene labels Apple's index understands.
Kind: Reads

doctor

What it does: Check that the Photos library is reachable, the engine starts, and this Mac has granted the permissions needed.
Kind: Reads

export_originals

What it does: Export the original files to a folder on this Mac.
Kind: Reads

favorite_photos

What it does: Mark items as favourites, or clear the mark.
Kind: Writes

set_photo_title

What it does: Set the title on one item, as shown in Photos.
Kind: Writes

set_photo_description

What it does: Set the description, the caption field Photos shows under an item.
Kind: Writes

add_keywords

What it does: Add keywords to items.
Kind: Writes

add_to_album

What it does: Add items to an album, creating it if it does not exist.
Kind: Writes

archive_photos

What it does: Move items into an album for the user to review and empty by hand.
Kind: Asks first

Tool	What it does	Kind
`search_photos`	Search the entire Photos library through Apple's own on-device index: what a picture looks like, text read inside it, the place, the activity, and any named faces.	Reads
`look_at_photos`	Return the images themselves so they can be looked at, rather than reasoned about from filenames and labels.	Reads
`photo_info`	Everything Photos knows about specific items: date, place, camera and lens, dimensions, albums, keywords, faces, and whether the original is on this Mac or still in iCloud.	Reads
`library_stats`	Real totals for the whole library in one call: items, photos against videos, favourites, screenshots, how many carry ML labels, text or a place, named people, and every album.	Reads
`list_vocabulary`	List the scene labels Apple's index understands.	Reads
`doctor`	Check that the Photos library is reachable, the engine starts, and this Mac has granted the permissions needed.	Reads
`export_originals`	Export the original files to a folder on this Mac.	Reads
`favorite_photos`	Mark items as favourites, or clear the mark.	Writes
`set_photo_title`	Set the title on one item, as shown in Photos.	Writes
`set_photo_description`	Set the description, the caption field Photos shows under an item.	Writes
`add_keywords`	Add keywords to items.	Writes
`add_to_album`	Add items to an album, creating it if it does not exist.	Writes
`archive_photos`	Move items into an album for the user to review and empty by hand.	Asks first

Is the Apple Photos MCP server safe?

Organizing works from the start, because that's the point of the tool. Nothing here can delete a photo, since macOS doesn't allow it for any app. Archiving moves photos into an album you empty yourself, and it's the only tool that asks first, marked Asks first in the tool tables above.

Everything else is one click to undo in Photos, so it doesn't ask.

Make it read-only

Set APPLE_PHOTOS_READ_ONLY=1 and every write disappears from the tool list, leaving 7 reading tools. That's the right setting for an agent working on its own.

Keep a log of every write

Set APPLE_PHOTOS_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

⚠️

Watch out: Text read out of your photos is mostly things you photographed, so the risk is far smaller than a public feed. A screenshot of a web page can still carry instructions, so use APPLE_PHOTOS_READ_ONLY=1 for unattended work.

Your data

Nothing leaves your Mac. There's no server of ours, no account and no tracking of any kind.

The search index and the previews live in ~/.apple-photos-mcp/, and deleting that folder clears them. The previews your AI looks at are sent to the AI you're talking to, like attaching a photo to a chat yourself.

Apple Photos MCP server settings

Every setting is optional, as an environment variable in your app's config.

APPLE_PHOTOS_READ_ONLY

Default: off
What it does: 1 hides every write

APPLE_PHOTOS_AUDIT_LOG

Default: off
What it does: Logs every attempted write to a file

APPLE_PHOTOS_LIBRARY

Default: the last one opened
What it does: Points at a specific Photos library

APPLE_PHOTOS_EXPORT_DIR

Default: ~/Downloads/Photos Exports
What it does: Sets where exports go

APPLE_PHOTOS_PREVIEW_MAX

Default: 8
What it does: Sets how many photos one look shows

APPLE_PHOTOS_WRITE_BATCH_MAX

Default: 100
What it does: Sets the most photos one change can touch

APPLE_PHOTOS_ARCHIVE_ALBUM

Default: Archived by Claude
What it does: Names the album archived photos go into

Variable	Default	What it does
`APPLE_PHOTOS_READ_ONLY`	off	`1` hides every write
`APPLE_PHOTOS_AUDIT_LOG`	off	Logs every attempted write to a file
`APPLE_PHOTOS_LIBRARY`	the last one opened	Points at a specific Photos library
`APPLE_PHOTOS_EXPORT_DIR`	`~/Downloads/Photos Exports`	Sets where exports go
`APPLE_PHOTOS_PREVIEW_MAX`	`8`	Sets how many photos one look shows
`APPLE_PHOTOS_WRITE_BATCH_MAX`	`100`	Sets the most photos one change can touch
`APPLE_PHOTOS_ARCHIVE_ALBUM`	`Archived by Claude`	Names the album archived photos go into

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

What you see	What to do
Permission denied reading the library	Turn on Full Disk Access, then quit the app with Cmd+Q
The server doesn't show up in your app	The config has a bad comma. Paste it into a JSON checker
`npx: command not found`	The app can't see your PATH. Use the full path from `which npx`
Reading works, changes fail	Approve the Photos control popup, or allow it under Privacy & Security, then Automation
The first search takes half a minute	It's building the index once, about 25 seconds for 37,000 photos
An obvious word finds nothing	Apple has no such label. Check `unmatched_terms`, or run `list_vocabulary`

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free tools for your photos

Turn photos into a carousel for Instagram, or into images to share.

Instagram carousel generator Post image generator

Apple Photos MCP Server FAQs

Here are the questions people ask most about the Apple Photos MCP server and CLI.

What is the Apple Photos MCP server & CLI?

The Apple Photos MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor search and organize your own Apple Photos library.

It has 13 tools to search, look at, organize and export your own library, entirely on your Mac, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

What is an MCP server?

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

What is the Apple Photos CLI?

The Apple Photos CLI is the same program as the Apple Photos MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

Should I use the Apple Photos MCP server or the CLI?

Use the Apple Photos MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Is the Apple Photos MCP server free?

Yes, the Apple Photos MCP server is free and open source under the MIT license.

It needs no account and no key, just your Mac.

Does the Apple Photos MCP server upload my photos anywhere?

No, the Apple Photos MCP server works entirely on your Mac, with no account and no tracking.

Only the previews your AI looks at go to that AI, like attaching a photo to a chat.

Can the Apple Photos MCP server delete photos?

No, the Apple Photos MCP server can't delete a photo, because macOS doesn't allow it for any app.

Archiving moves photos into an album you empty yourself, and it asks for a confirm check first.

Does the Apple Photos MCP server work on Windows?

No, the Apple Photos MCP server only runs on a Mac, because it reads the Photos library macOS keeps.

It needs Full Disk Access for the app that runs it.

Why can't the Apple Photos MCP server find an obvious word?

The Apple Photos MCP server searches Apple's own labels, a closed list of about 1,500 words.

When a word isn't on it, the result says so, and list_vocabulary shows every word Apple knows.

Which AI apps does the Apple Photos MCP server work with?

The Apple Photos MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes, on your Mac.

Who built the Apple Photos MCP server?

Navid Moazzez built the Apple Photos MCP server and maintains it.

The code is on GitHub under the MIT license, and the package is on npm.