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

photo-cli mcp [options]

​
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

​
--input, -i
string
Path to the archive folder containing the photo-cli.sqlite3 database. Defaults to the current working directory.
​
--custom-database-path, -j
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:
ToolDescription
search_photosSearch photos by date range, location text, or limit. Returns paths, dates, and location info.
get_photoGet full metadata for a specific photo by its archive file path.
list_albumsList all albums with ID, name, type, creation date, and configuration.
get_statisticsGet photo counts grouped by year, month, country, city, or camera model.
find_near_locationFind photos taken near a GPS coordinate within a given radius (Haversine formula).
list_photos_by_album_idList photos belonging to an album by its numeric ID.
list_photos_by_album_nameList photos belonging to an album by its name.
list_photos_by_exact_dateList photos matching an exact date (year, month, day). All parameters are optional.
list_photos_by_date_rangeList photos within a date range. Both start and end dates are inclusive.
open_photos_by_album_idOpen photos belonging to an album by its numeric ID in the default viewer (macOS Preview).
open_photos_by_album_nameOpen photos belonging to an album by its name in the default viewer (macOS Preview).
open_photos_by_exact_dateOpen photos matching an exact date in the default viewer (macOS Preview).
open_photos_by_date_rangeOpen photos within a date range in the default viewer (macOS Preview).

​
Setup

​
Claude Code (CLI)

claude mcp add photo-cli --scope user -- photo-cli mcp --input /path/to/archive-folder

​
Claude Desktop

Add the following to your claude_desktop_config.json: 
"mcpServers": {
  "photo-cli": {
    "command": "{photo-cli-executable-path}",
    "args": [
      "mcp",
      "--input",
      "{archive-folder-path}"
    ]
  }
}

"mcpServers": {
  "photo-cli": {
    "command": "/Users/{your-user}/.dotnet/tools/photo-cli",
    "args": [
      "mcp",
      "--input",
      "/Users/{your-user}/{archive-folder}"
    ]
  }
}

​
VS Code

Add to .vscode/mcp.json or your user settings: 
"photo-cli": {
  "type": "stdio",
  "command": "{photo-cli-executable-path}",
  "args": [
    "mcp",
    "--input",
    "{archive-folder-path}"
  ]
}

"photo-cli": {
  "type": "stdio",
  "command": "/Users/{your-user}/.dotnet/tools/photo-cli",
  "args": [
    "mcp",
    "--input",
    "/Users/{your-user}/{archive-folder}"
  ]
}

​
MCP Inspector (debugging)

Use the MCP Inspector to test and debug the server interactively: 
npx @modelcontextprotocol/inspector photo-cli mcp --input {archive-folder-path}