@thenavidm/apple-photos-mcp-cli 1.0.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@thenavidm/apple-photos-mcp-cli",
+  "version": "1.0.0",
+  "description": "Apple Photos MCP server and CLI for Claude Code and AI agents. 13 tools to search, look at, organise and export your own Photos library, entirely on your Mac.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "apple-photos-mcp": "dist/index.js",
+    "apple-photos-cli": "dist/index.js"
+  },
+  "engines": { "node": ">=20" },
+  "os": ["darwin"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "author": "Navid Moazzez (https://navid.me)",
+  "homepage": "https://navid.me",
+  "repository": { "type": "git", "url": "git+https://github.com/navidmoazzez/apple-photos-mcp.git" },
+  "bugs": { "url": "https://github.com/navidmoazzez/apple-photos-mcp/issues" },
+  "keywords": ["mcp","model-context-protocol","apple-photos","photos","macos","mcp-server","claude","claude-code","ai-agents","llm-tools","cli"],
+  "files": ["dist","src","pyproject.toml","README.md","SKILL.md","LICENSE"]
+}

package/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+# PyPI has no scopes, so an owner prefix is the closest equivalent to the
+# @thenavidm npm scope the TypeScript servers use. Applied even though the bare
+# name is free, so both Python packages are named the same way. The installed
+# command is still `apple-photos-mcp`.
+name = "thenavidm-apple-photos-mcp"
+version = "0.1.0"
+description = "Apple Photos MCP server for Claude Code and AI agents. Photo search, scene labels, text in images, faces, places, albums, previews, and exports."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Navid Moazzez" }]
+keywords = ["mcp", "model-context-protocol", "apple-photos", "photos", "macos", "osxphotos", "claude", "claude-code", "ai-agents", "llm-tools"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: MacOS X",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  # macOS only. Both pull in pyobjc, which refuses to build anywhere else:
+  # "error: PyObjC requires macOS to build". Without these markers a plain
+  # `pip install` fails on Linux instead of installing and then telling the
+  # user this server needs a Mac.
+  "osxphotos>=0.72; sys_platform == 'darwin'",
+  "photoscript>=0.3.0; sys_platform == 'darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/navidmoazzez/apple-photos-mcp"
+Issues = "https://github.com/navidmoazzez/apple-photos-mcp/issues"
+Author = "https://navid.me"
+
+[project.scripts]
+apple-photos-mcp = "apple_photos_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apple_photos_mcp"]
+
+# SKILL.md ships inside the package so an agent that installs the server also
+# learns how to drive it. The README teaches a human to install it.
+force-include = { "SKILL.md" = "apple_photos_mcp/SKILL.md" }
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "SIM", "UP", "PL", "RUF"]
+ignore = [
+  # An MCP tool must never take the server down. Every tool body catches
+  # broadly on purpose and returns the error to the model as data, which is the
+  # only behavior a client can do anything useful with.
+  "BLE001",
+  "PLR0913",  # tool signatures are wide because search filters are wide
+  "PLR2004",  # score tuning constants read better inline than as names
+  "PLR0917",  # search_photos takes many filters on purpose; they are the API
+  # osxphotos and photoscript are slow to import and pull in native deps. They
+  # are imported at point of use so the server starts fast and so `doctor` can
+  # still explain itself on a machine where they cannot load at all.
+  "PLC0415",
+  # Filters.keep, the ranking loop and the tool registry are each one long flat
+  # sequence by design. Splitting them into helpers to satisfy a counter would
+  # scatter logic that is only readable when read top to bottom.
+  "PLR0911", "PLR0912", "PLR0915", "SIM103",
+]

package/src/apple_photos_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for the macOS Apple Photos library."""
+
+__version__ = "0.1.0"

package/src/apple_photos_mcp/__main__.py

@@ -0,0 +1,40 @@
+"""Entry point: ``apple-photos-mcp`` (stdio) and ``apple-photos-mcp doctor``."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+
+from .config import Config
+
+
+def main() -> int:
+    # stderr only. Anything on stdout corrupts the JSON-RPC stream.
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+
+    args = sys.argv[1:]
+    config = Config.from_env()
+
+    if args and args[0] in {"-v", "--version"}:
+        from . import __version__
+
+        print(__version__)
+        return 0
+
+    if args and args[0] == "doctor":
+        from . import doctor as doctor_mod
+        from .library import PhotosLibrary
+
+        report = doctor_mod.run(config, PhotosLibrary(config))
+        print(json.dumps(report, indent=2, default=str))
+        return 0 if report["ok"] else 1
+
+    from .server import build_server
+
+    build_server(config).run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apple_photos_mcp/config.py

@@ -0,0 +1,82 @@
+"""Configuration, resolved once from the environment.
+
+Settings are environment variables, not CLI flags, because a user editing a
+client config is already inside a JSON `env` block and flags mean editing
+`args` separately.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+ENV_PREFIX = "APPLE_PHOTOS_"
+
+
+def _flag(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(ENV_PREFIX + name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(ENV_PREFIX + name, "").strip())
+    except (TypeError, ValueError):
+        return default
+
+
+def _path(name: str) -> Path | None:
+    raw = os.environ.get(ENV_PREFIX + name)
+    return Path(raw).expanduser() if raw else None
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved server configuration."""
+
+    #: Explicit .photoslibrary path. ``None`` means "whichever Photos opened last".
+    library: Path | None = None
+
+    #: Removes every write tool from the tool list rather than erroring when one
+    #: is called. A model cannot call a tool it cannot see, and an error is an
+    #: invitation to retry differently. This is the real defense for an agent
+    #: working unattended.
+    read_only: bool = False
+
+    #: One JSON line per attempted write, allowed and blocked alike.
+    audit_log: Path | None = None
+
+    #: Where ``export_originals`` writes when the caller does not name a folder.
+    export_dir: Path = Path.home() / "Downloads" / "Photos Exports"
+
+    #: Where ``look_at_photos`` caches the previews it hands to the model.
+    preview_dir: Path = Path.home() / ".apple-photos-mcp" / "previews"
+
+    #: Longest edge, in pixels, of a preview. Small enough to stay cheap in context.
+    preview_px: int = 640
+
+    #: Most items a single ``look_at_photos`` call will render.
+    preview_max: int = 8
+
+    #: Most items any single write touches. A typo should not restructure a library.
+    write_batch_max: int = 100
+
+    #: Album that ``archive_photos`` moves items into. Apple forbids scripted deletion.
+    archive_album: str = "Archived by Claude"
+
+    @classmethod
+    def from_env(cls) -> Config:
+        return cls(
+            library=_path("LIBRARY"),
+            read_only=_flag("READ_ONLY"),
+            audit_log=_path("AUDIT_LOG"),
+            export_dir=_path("EXPORT_DIR") or cls.export_dir,
+            preview_dir=_path("PREVIEW_DIR") or cls.preview_dir,
+            preview_px=_int("PREVIEW_PX", cls.preview_px),
+            preview_max=_int("PREVIEW_MAX", cls.preview_max),
+            write_batch_max=_int("WRITE_BATCH_MAX", cls.write_batch_max),
+            archive_album=os.environ.get(ENV_PREFIX + "ARCHIVE_ALBUM") or cls.archive_album,
+        )

package/src/apple_photos_mcp/doctor.py

@@ -0,0 +1,162 @@
+"""Self-diagnosis.
+
+Almost every failure with a Photos integration is one of four things, and all
+four are invisible from inside a chat window: the wrong OS, a missing Full Disk
+Access grant, a library that cannot be found, or writes being off when the user
+expected them on. ``doctor`` names which one it is and what to click.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import Config
+from .library import PhotosLibrary
+
+
+def _check(name: str, ok: bool, detail: str, fix: str = "") -> dict[str, Any]:
+    out = {"check": name, "ok": ok, "detail": detail}
+    if not ok and fix:
+        out["fix"] = fix
+    return out
+
+
+def run(config: Config, lib: PhotosLibrary) -> dict[str, Any]:
+    checks: list[dict[str, Any]] = []
+
+    is_mac = sys.platform == "darwin"
+    checks.append(
+        _check(
+            "macOS",
+            is_mac,
+            f"{platform.system()} {platform.mac_ver()[0] or platform.release()}",
+            "Apple Photos exists only on macOS. This server cannot run anywhere else.",
+        )
+    )
+
+    checks.append(
+        _check(
+            "python",
+            sys.version_info >= (3, 11),
+            f"Python {platform.python_version()}",
+            "Python 3.11 or newer is required.",
+        )
+    )
+
+    checks.append(
+        _check(
+            "sips",
+            shutil.which("sips") is not None,
+            "sips is used to render previews and ships with macOS",
+            "sips is missing, which should be impossible on a healthy macOS install.",
+        )
+    )
+
+    # Locating the library.
+    lib_path: Path | None = None
+    try:
+        lib_path = lib._library_path()
+        found = lib_path.exists()
+        checks.append(
+            _check(
+                "library found",
+                found,
+                str(lib_path),
+                "Open Photos once so macOS records a library path, or set "
+                "APPLE_PHOTOS_MCP_LIBRARY to a .photoslibrary folder.",
+            )
+        )
+    except Exception as exc:
+        checks.append(
+            _check(
+                "library found",
+                False,
+                str(exc),
+                "Set APPLE_PHOTOS_MCP_LIBRARY to your .photoslibrary path.",
+            )
+        )
+
+    # Full Disk Access is the single most common failure, and it presents as a
+    # permission error on the library's SQLite rather than as anything obvious.
+    readable = False
+    detail = "not attempted"
+    if lib_path and lib_path.exists():
+        db = lib_path / "database" / "Photos.sqlite"
+        try:
+            with open(db, "rb") as fh:
+                fh.read(16)
+            readable = True
+            detail = "library database is readable"
+        except PermissionError:
+            detail = "permission denied reading the library database"
+        except FileNotFoundError:
+            detail = "library database not found at the expected path"
+        except OSError as exc:
+            detail = str(exc)
+    checks.append(
+        _check(
+            "full disk access",
+            readable,
+            detail,
+            "Give the app that runs this server Full Disk Access: System Settings > "
+            "Privacy & Security > Full Disk Access. For Claude Desktop add Claude; for "
+            "a terminal add Terminal or iTerm. Then fully quit and reopen it.",
+        )
+    )
+
+    # Index.
+    if readable:
+        try:
+            stats = lib.stats()
+            checks.append(
+                _check(
+                    "index",
+                    True,
+                    f"{stats['total']} assets indexed "
+                    f"({stats['with_ml_labels']} with ML labels, "
+                    f"{stats['with_text_in_image']} with readable text)",
+                )
+            )
+            if stats["not_downloaded_to_mac"]:
+                checks.append(
+                    _check(
+                        "icloud",
+                        True,
+                        f"{stats['not_downloaded_to_mac']} of {stats['total']} assets live "
+                        f"in iCloud and have no full-size local file. Previews still work "
+                        f"(they come from Apple's own thumbnails); exporting an original "
+                        f"downloads it first and is slower.",
+                    )
+                )
+        except Exception as exc:
+            checks.append(
+                _check("index", False, str(exc), "Run doctor again after opening Photos once.")
+            )
+
+    checks.append(
+        _check(
+            "writes",
+            True,
+            "read-only (APPLE_PHOTOS_READ_ONLY is set)" if config.read_only else "enabled",
+        )
+    )
+    checks[-1]["note"] = (
+        "Write tools are hidden in read-only mode. Unset APPLE_PHOTOS_READ_ONLY to "
+        "restore them."
+        if config.read_only
+        else "Organizing works. archive_photos asks for confirm first, and nothing "
+        "can permanently delete a photo."
+    )
+    if config.audit_log:
+        checks.append(_check("audit log", True, str(config.audit_log)))
+
+    failed = [c for c in checks if not c["ok"]]
+    return {
+        "ok": not failed,
+        "summary": "All checks passed." if not failed else f"{len(failed)} check(s) failed.",
+        "checks": checks,
+    }