Apple Photos MCP Server & CLI

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 two 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.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Apple Photos. I explain how the parts fit together in how to build an AI operating system, and here's how I use AI myself.

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.

It works well next to my Google Photos MCP server and iMessage MCP server, so your AI can build albums in Google Photos and send a photo to someone in Messages in the same chat. Every server I've made is on my MCP servers page.

For the photos themselves, my free HEIC to JPG converter and image resizer help too.

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.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

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.

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.

In Claude Code, /mcp also shows whether the Apple Photos server is connected. It's one of the Claude Code commands worth knowing.

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, apple-photos-cli which <words> finds the command for a task, and apple-photos-cli <command> --help shows what a command takes. Archiving asks first, like it does for your AI.

apple-photos-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

A script can branch on the exit code:

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.

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 seven 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 October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.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

The tables below list all 13 tools, grouped the way the repo groups them. Of these, seven only read, and six change something in your library.

Search, look and organize

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.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

• Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
• An app that can show forms asks you in a form.
• Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
• An agent with no person to ask needs APPLE_PHOTOS_CONFIRM=model, so its confirm: true counts in every app.
• In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Apple Photos.

Make it read-only

Set APPLE_PHOTOS_READ_ONLY=1 and every write disappears from the tool list, leaving seven 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, with what it was about to do and who approved it.

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.

Troubleshooting

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

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.