Skip to main content
photo-cli mcp starts a Model Context Protocol (MCP) stdio server that exposes your archived photo database to AI assistants. This lets tools like Claude Desktop, Claude Code, and VS Code query your photos conversationally — searching by date, location, album, or proximity to a GPS coordinate.

Synopsis

Prerequisites

  • An archive folder created with photo-cli archive that contains the photo-cli.sqlite3 database.
  • .NET runtime available, or use the self-contained executable.

Arguments

string
Path to the archive folder containing the photo-cli.sqlite3 database. Defaults to the current working directory.
string
Custom file system path directly to the SQLite database file, bypassing the default database location within the archive folder. When provided, the database is read from this exact path instead of [archive-folder]/photo-cli.sqlite3.

MCP tools exposed

When a client connects, photo-cli registers the following tools: The view_* tools return downscaled JPEG images (long edge maxDimension, default 1280, max 2048) that render inline in the chat on any platform. Multi-photo tools show at most maxCount photos (default 6, max 20), sorted by date taken. Use open_* when you want the full-resolution original open in macOS Preview.

Setup

Claude Code (CLI)

Claude Desktop

Add the following to your claude_desktop_config.json:

VS Code

Add to .vscode/mcp.json or your user settings:

MCP Inspector (debugging)

Use the MCP Inspector to test and debug the server interactively: