Skip to main content

Documentation Index

Fetch the complete documentation index at: https://photocli.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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}