Photo Organizer

Give your agent the tools to find, group, and export your photos.

Local photo organization · Persistent selections · Preview before export

Quick start · Connect your agent · Tool reference · Roadmap

English · 简体中文

Turn a folder of photos into a selection you can refine, a plan you can inspect, and an organized export. Photo Organizer gives tool-capable agents a shared local engine through a Skill, MCP server, or JSON CLI. Originals stay in place.

“Find the landscape photos, group them by month, and copy them into a new folder.”

“From that selection, keep only the photos from 2024.”

“Export smaller JPEG copies of these photos for sharing.”

These are example requests for a connected agent. The agent interprets your request; the engine handles selections, plans, and file operations.

flowchart LR
    A[Local photos] --> B[Scan & search]
    B --> C[Saved selection]
    C --> D[Preview plan]
    D --> E[Album / Copy / Compress]
    C -->|Refine the same selection| C

Why Photo Organizer?

Related MCP server: Apple Photos MCP

Quick start

Requirements: Python 3.11+, macOS or Linux with POSIX file APIs. Local test evidence is currently from macOS; Linux CI is configured, with remote acceptance still pending. Windows is unsupported.

1. Install from source

git clone https://github.com/berhannnnd/photo-organizer.git
cd photo-organizer
python3 -m venv .venv
. .venv/bin/activate
python -m pip install '.[mcp]'

For CLI-only use, install with python -m pip install .. The core depends on Pillow; the mcp extra adds the official MCP Python SDK.

2. Scan and select

Replace the absolute paths below with your own. Keep the state directory outside your photo folders and this checkout, and reuse it across sessions.

photo-organizer --state /absolute/library-state call capabilities
photo-organizer --state /absolute/library-state call scan --args '{"root":"/absolute/photos"}'
photo-organizer --state /absolute/library-state call search --args '{"rule":{"orientation":"landscape"}}'

The search response includes data.result_set_id. Use that value as RESULT_ID below.

3. Preview, then export

photo-organizer --state /absolute/library-state call plan --args '{"spec":{"result_set_id":"RESULT_ID","group_by":"month"},"mode":"copy","target":"/absolute/organized"}'

Inspect the returned groups, selected count, and mode. Use the returned data.plan_id as PLAN_ID, then execute within the user's authorization:

photo-organizer --state /absolute/library-state call apply --args '{"plan_id":"PLAN_ID"}'

Photos without an EXIF capture date go into date-unknown; download times are not used as capture dates. The output directory must not overlap any source root. Read status, error, and per-action errors—partial failure is not a completed export.

Connect your agent

Install or reference the Skill using your host's Skill mechanism. It is also bundled under share/photo-organizer/skills/photo-organizer relative to the installation prefix.

For an MCP host, adapt its configuration to launch the installed executable:

{
  "mcpServers": {
    "photo-organizer": {
      "command": "/absolute/photo-organizer/.venv/bin/photo-organizer-mcp",
      "args": ["--state", "/absolute/library-state"]
    }
  }
}

Replace both paths. Use the same state directory for the CLI and MCP server. Start with photo_capabilities to discover the installed engine's supported operations.

The server runs with your local user permissions. Connect it to trusted hosts and use authorized directories; the host controls tool authorization. It is a local process, not a remote multi-tenant service.

Add visual search when you need it

The metadata workflow above works without a model. Visual features require their own configuration and index coverage:

Copy the provider example outside the repository. Set the exact model, endpoint, and named API-key environment variable, then start with a small authorized batch:

photo-organizer --state /absolute/library-state index --config /absolute/provider.json --limit 5

This sends derived images to the configured provider. The alpha supports Anthropic-compatible image requests. Credentials belong in the named environment variable, not in the repository. CC Switch import is optional legacy functionality.

For local retrieval, see the Ollama probe notes for the tested model and evidence scope, and the tool reference for index and retrieval operations. Models are not downloaded automatically.

Ranked candidates are not verified matches. Review them before claiming semantic accuracy, or explicitly choose to organize the candidate set.

Project status and documentation

Photo Organizer is under active development. The PRD defines the complete product target; the delivery checklist tracks release requirements. Discover runtime capabilities before relying on a feature. Local tests and small model probes do not establish full-library quality or cross-host readiness.

Contributing

Bug reports, reproducible examples, documentation improvements, and code contributions are welcome. Start with CONTRIBUTING.md, or open an issue.

python -m pip install '.[mcp,dev]'
python -m unittest discover -s tests -v
python -m build

License

Code is licensed under MIT. Photo datasets retain their original source licenses. The local 1,000-photo development dataset is not bundled or relicensed by this project.