proton-drive-mcp 1.0.24 → 1.0.26

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.25 — 2026-08-04
+
+### Added
+- **`photos_list_albums`** — list all Proton Photos albums (`album list`); returns name, photoCount, isShared, creationTime
+- **`photos_create_album`** — create a new empty album by name (`album create <name>`)
+- **`photos_delete_album`** — delete an album with optional `--force` (delete even if non-empty) and `--save` (preserve photos in timeline) flags; requires `confirmed: true`
+- **`photos_list_album_photos`** — list photos in an album by path; returns nodeUids (`album photos <albumPath>`)
+- **`photos_add_to_album`** — add a photo from your library to an album (`album add-photo <albumPath> <photoPath>`)
+- **`photos_remove_from_album`** — remove a photo from an album without deleting it from your library (`album remove-photo <albumPath> <photoPath>`)
+- All 6 tools also available as CLI subcommands: `album list/create/delete/photos/add-photo/remove-photo`
+- Album paths use `/albums/<name>` prefix; photo paths use `/photos/<filename>` prefix
+
 ## 1.0.24 — 2026-08-04
 
 ### Added

package/README.md

@@ -24,12 +24,13 @@
 
 ---
 
-Give Claude Desktop (or any MCP client) full access to your Proton Drive: list folders, upload and download files, invite collaborators, manage sharing, and handle trash — all with end-to-end encryption intact. The same capabilities are available as a full CLI for scripting, backups, and cron.
+Give Claude Desktop (or any MCP client) full access to your Proton Drive and Proton Photos: list folders, upload and download files, invite collaborators, manage sharing, handle trash, and manage photo albums — all with end-to-end encryption intact. The same capabilities are available as a full CLI for scripting, backups, and cron.
 
 ## What you get
 
 - **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
-- **Full CLI** — same 23 operations, scriptable and pipeable, works in cron and shell scripts
+- **Proton Photos album management** — list albums, create/delete albums, add and remove photos
+- **Full CLI** — same 29 operations, scriptable and pipeable, works in cron and shell scripts
 - **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
 - **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
 - **Privacy-native** — end-to-end encryption is handled by Proton's own CLI; this server is just a thin MCP wrapper
@@ -231,6 +232,9 @@ proton-drive-cli share status /my-files/Projects
 ### Invitations
 `drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
 
+### Photos
+`photos_list_albums` · `photos_create_album` · `photos_delete_album` · `photos_list_album_photos` · `photos_add_to_album` · `photos_remove_from_album`
+
 ---
 
 ## Tool reference
@@ -260,6 +264,12 @@ proton-drive-cli share status /my-files/Projects
 | `drive_invitation_accept` | Accept a pending invitation | `uid` (from `drive_list_invitations`) |
 | `drive_invitation_reject` | Reject a pending invitation ⚠️ | `uid` (from `drive_list_invitations`) |
 | `drive_share_leave` | Leave a shared folder shared with you ⚠️ | `path` |
+| `photos_list_albums` | List all Proton Photos albums | — |
+| `photos_create_album` | Create a new empty album | `name` |
+| `photos_delete_album` | Delete an album ⚠️ | `albumPath`, `confirmed: true`, `force?`, `save?` |
+| `photos_list_album_photos` | List photos in an album | `albumPath` |
+| `photos_add_to_album` | Add a photo from your library to an album | `albumPath`, `photoPath` |
+| `photos_remove_from_album` | Remove a photo from an album (keeps it in library) ⚠️ | `albumPath`, `photoPath` |
 
 > ⚠️ **Destructive tools** require `confirmed: true`. Use `drive_list_trash` first so you know what will be deleted, then pass `confirmed: true` to proceed.
 

package/dist/cli.js

@@ -52,6 +52,12 @@ Commands:
   trash list                               List trash contents
   trash empty                              Permanently delete all trash
   restore <path>                           Restore from trash
+  album list                               List all photo albums
+  album create <name>                      Create a new album
+  album delete <path> [--force] [--save]  Delete an album
+  album photos <path>                      List photos in an album
+  album add-photo <album> <photo>          Add a photo to an album
+  album remove-photo <album> <photo>       Remove a photo from an album
 
 Flags:
   --json                                   Machine-readable JSON output (one line)
@@ -304,6 +310,49 @@ async function run() {
                 process.exit(1);
             }
             break;
+        case "album":
+            if (sub === "list" || sub === "ls") {
+                print(await drive.listAlbums());
+            }
+            else if (sub === "create") {
+                const albumName = rest[0];
+                if (!albumName) {
+                    console.error("Usage: album create <name>");
+                    process.exit(1);
+                }
+                await drive.createAlbum(albumName);
+                console.log(`Album created: ${albumName}`);
+            }
+            else if (sub === "delete") {
+                const albumPath = requirePath(rest[0], "album delete <path> [--force] [--save] --confirm");
+                if (!args.includes("--confirm")) {
+                    console.error(`This will delete album: ${albumPath}\nPass --confirm to proceed.`);
+                    process.exit(1);
+                }
+                await drive.deleteAlbum(albumPath, args.includes("--force"), args.includes("--save"));
+                console.log(`Album deleted: ${albumPath}`);
+            }
+            else if (sub === "photos") {
+                const albumPath = requirePath(rest[0], "album photos <path>");
+                print(await drive.listAlbumPhotos(albumPath));
+            }
+            else if (sub === "add-photo") {
+                const albumPath = requirePath(rest[0], "album add-photo <album-path> <photo-path>");
+                const photoPath = requirePath(rest[1], "album add-photo <album-path> <photo-path>");
+                await drive.addPhotoToAlbum(albumPath, photoPath);
+                console.log(`Added ${photoPath} to ${albumPath}`);
+            }
+            else if (sub === "remove-photo") {
+                const albumPath = requirePath(rest[0], "album remove-photo <album-path> <photo-path>");
+                const photoPath = requirePath(rest[1], "album remove-photo <album-path> <photo-path>");
+                await drive.removePhotoFromAlbum(albumPath, photoPath);
+                console.log(`Removed ${photoPath} from ${albumPath}`);
+            }
+            else {
+                console.error("Usage: album list | album create <name> | album delete <path> | album photos <path> | album add-photo <album> <photo> | album remove-photo <album> <photo>");
+                process.exit(1);
+            }
+            break;
         default:
             console.error(`Unknown command: ${cmd}`);
             usage();

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { createRequire } from "node:module";
 import { DriveService } from "./services/drive.js";
+import { isMainModule } from "./utils/isMainModule.js";
 import { checkCliAvailable } from "./utils/subprocess.js";
 import { DriveCliNotFoundError, DriveCliError, DriveNotAuthenticatedError, DriveParseError, } from "./utils/errors.js";
 import { validateRemotePath, validateLocalPath, validateEmail, validateMessage } from "./utils/validation.js";
@@ -447,6 +448,130 @@ const TOOLS = [
             additionalProperties: false,
         },
     },
+    // Photos / Albums
+    {
+        name: "photos_list_albums",
+        description: "List all photo albums in Proton Photos. Requires authentication. " +
+            "Returns [{name, photoCount, isShared, creationTime?}]. " +
+            "Album paths are /albums/<name> — use the name from this list to build paths for other album tools. " +
+            "Do not use to list regular Drive folders — use drive_list instead.",
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
+    },
+    {
+        name: "photos_create_album",
+        description: "Create a new empty photo album in Proton Photos. Requires authentication. " +
+            "Pass the album name (not a path) — the album is created at /albums/<name>. " +
+            "Fails if an album with that name already exists.",
+        annotations: { destructiveHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Name of the new album. E.g. 'Vacation 2024'. Must be non-empty.",
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "photos_delete_album",
+        description: "Delete a Proton Photos album. Requires authentication and confirmed=true. " +
+            "By default refuses to delete an album that still contains photos — pass force=true to override. " +
+            "By default photos are removed from the album but kept in your timeline — pass save=true to explicitly preserve them in your timeline before deleting. " +
+            "albumPath must start with /albums/. " +
+            "Always show the user the album name and photo count (from photos_list_albums) before calling.",
+        annotations: { destructiveHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                albumPath: {
+                    type: "string",
+                    description: "Absolute path of the album to delete. Must start with /albums/. E.g. /albums/Vacation 2024",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Must be true. Confirms the user has acknowledged the deletion.",
+                },
+                force: {
+                    type: "boolean",
+                    description: "If true, delete even if the album still contains photos. Default false.",
+                },
+                save: {
+                    type: "boolean",
+                    description: "If true, save album photos to your timeline before deleting. Default false.",
+                },
+            },
+            required: ["albumPath", "confirmed"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "photos_list_album_photos",
+        description: "List the photos in a Proton Photos album. Requires authentication. " +
+            "Returns [{nodeUid}] — photo node UIDs. " +
+            "albumPath must start with /albums/. " +
+            "To add or remove photos, use their Drive path under /photos/ (not the nodeUid).",
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                albumPath: {
+                    type: "string",
+                    description: "Absolute path of the album. Must start with /albums/. E.g. /albums/Vacation 2024",
+                },
+            },
+            required: ["albumPath"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "photos_add_to_album",
+        description: "Add a photo from your Proton Photos library to an album. Requires authentication. " +
+            "albumPath must start with /albums/; photoPath must start with /photos/. " +
+            "The photo must already exist in your library — this does not upload new photos. " +
+            "Use photos_list_albums to find album paths.",
+        annotations: { destructiveHint: false },
+        inputSchema: {
+            type: "object",
+            properties: {
+                albumPath: {
+                    type: "string",
+                    description: "Absolute path of the album. Must start with /albums/. E.g. /albums/Vacation 2024",
+                },
+                photoPath: {
+                    type: "string",
+                    description: "Absolute path of the photo in your library. Must start with /photos/. E.g. /photos/IMG_001.jpg",
+                },
+            },
+            required: ["albumPath", "photoPath"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "photos_remove_from_album",
+        description: "Remove a photo from a Proton Photos album without deleting it from your library. Requires authentication. " +
+            "albumPath must start with /albums/; photoPath must start with /photos/. " +
+            "The photo is removed from the album only — it stays in your timeline.",
+        annotations: { destructiveHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                albumPath: {
+                    type: "string",
+                    description: "Absolute path of the album. Must start with /albums/. E.g. /albums/Vacation 2024",
+                },
+                photoPath: {
+                    type: "string",
+                    description: "Absolute path of the photo in the album. Must start with /photos/. E.g. /photos/IMG_001.jpg",
+                },
+            },
+            required: ["albumPath", "photoPath"],
+            additionalProperties: false,
+        },
+    },
     // Sync-folder tools (requires PROTON_DRIVE_SYNC_PATH env var)
     {
         name: "drive_read_file",
@@ -625,6 +750,49 @@ export async function main() {
                     await drive.shareLeave(leavePath);
                     return ok({ message: `Left shared folder: ${leavePath}` });
                 }
+                case "photos_list_albums":
+                    return ok(await drive.listAlbums());
+                case "photos_create_album": {
+                    if (typeof a.name !== "string" || !a.name.trim())
+                        return fail("name must be a non-empty string");
+                    await drive.createAlbum(a.name.trim());
+                    return ok({ message: `Album created: ${a.name.trim()}` });
+                }
+                case "photos_delete_album": {
+                    if (a.confirmed !== true)
+                        return fail("photos_delete_album requires confirmed=true. Show the user the album name and photo count first.");
+                    const albumDelPath = validateRemotePath(a.albumPath);
+                    if (!albumDelPath.startsWith("/albums/"))
+                        return fail("albumPath must start with /albums/");
+                    await drive.deleteAlbum(albumDelPath, a.force === true, a.save === true);
+                    return ok({ message: `Album deleted: ${albumDelPath}` });
+                }
+                case "photos_list_album_photos": {
+                    const albumListPath = validateRemotePath(a.albumPath);
+                    if (!albumListPath.startsWith("/albums/"))
+                        return fail("albumPath must start with /albums/");
+                    return ok(await drive.listAlbumPhotos(albumListPath));
+                }
+                case "photos_add_to_album": {
+                    const addAlbumPath = validateRemotePath(a.albumPath);
+                    const addPhotoPath = validateRemotePath(a.photoPath);
+                    if (!addAlbumPath.startsWith("/albums/"))
+                        return fail("albumPath must start with /albums/");
+                    if (!addPhotoPath.startsWith("/photos/"))
+                        return fail("photoPath must start with /photos/");
+                    await drive.addPhotoToAlbum(addAlbumPath, addPhotoPath);
+                    return ok({ message: `Added ${addPhotoPath} to ${addAlbumPath}` });
+                }
+                case "photos_remove_from_album": {
+                    const remAlbumPath = validateRemotePath(a.albumPath);
+                    const remPhotoPath = validateRemotePath(a.photoPath);
+                    if (!remAlbumPath.startsWith("/albums/"))
+                        return fail("albumPath must start with /albums/");
+                    if (!remPhotoPath.startsWith("/photos/"))
+                        return fail("photoPath must start with /photos/");
+                    await drive.removePhotoFromAlbum(remAlbumPath, remPhotoPath);
+                    return ok({ message: `Removed ${remPhotoPath} from ${remAlbumPath}` });
+                }
                 case "drive_read_file": {
                     const syncRoot = getSyncRoot();
                     if (!syncRoot)
@@ -655,7 +823,9 @@ export async function main() {
     await server.connect(transport);
     logger.info(`proton-drive-mcp v${VERSION} running`);
 }
-main().catch((err) => {
-    logger.error("Fatal:", err);
-    process.exit(1);
-});
+if (isMainModule(import.meta.url)) {
+    main().catch((err) => {
+        logger.error("Fatal:", err);
+        process.exit(1);
+    });
+}

package/dist/services/drive.js

@@ -171,4 +171,45 @@ export class DriveService {
     async shareLeave(remotePath) {
         await this.run(["sharing", "leave", remotePath]);
     }
+    // Photos / Albums
+    async listAlbums() {
+        const result = await this.run(["album", "list"]);
+        if (result === null)
+            return [];
+        if (!Array.isArray(result))
+            throw new DriveParseError(`Expected array from album list, got: ${JSON.stringify(result).slice(0, 100)}`);
+        return result.map((item) => ({
+            name: String(item.name ?? ""),
+            photoCount: typeof item.photoCount === "number" ? item.photoCount : 0,
+            isShared: Boolean(item.isShared ?? false),
+            creationTime: typeof item.creationTime === "string" ? item.creationTime : undefined,
+        }));
+    }
+    async createAlbum(name) {
+        await this.run(["album", "create", name]);
+    }
+    async deleteAlbum(albumPath, force, save) {
+        const args = ["album", "delete", albumPath];
+        if (force)
+            args.push("--force");
+        if (save)
+            args.push("--save");
+        await this.run(args);
+    }
+    async listAlbumPhotos(albumPath) {
+        const result = await this.run(["album", "photos", albumPath]);
+        if (result === null)
+            return [];
+        if (!Array.isArray(result))
+            throw new DriveParseError(`Expected array from album photos, got: ${JSON.stringify(result).slice(0, 100)}`);
+        return result.map((item) => ({
+            nodeUid: String(item.nodeUid ?? item.uid ?? ""),
+        }));
+    }
+    async addPhotoToAlbum(albumPath, photoPath) {
+        await this.run(["album", "add-photo", albumPath, photoPath]);
+    }
+    async removePhotoFromAlbum(albumPath, photoPath) {
+        await this.run(["album", "remove-photo", albumPath, photoPath]);
+    }
 }

package/dist/utils/isMainModule.js

@@ -0,0 +1,18 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Returns true when this module is the direct entry point (i.e. the script
+ * passed to `node`), false when it is being imported as a library.
+ *
+ * Equivalent to `require.main === module` in CommonJS.
+ */
+export function isMainModule(importMetaUrl) {
+    const entryPoint = process.argv[1];
+    if (!entryPoint)
+        return false;
+    try {
+        return fileURLToPath(importMetaUrl) === entryPoint;
+    }
+    catch {
+        return false;
+    }
+}

package/glama.json

@@ -102,6 +102,30 @@
     {
       "name": "drive_share_leave",
       "description": "Leave a Proton Drive folder that was shared with you by another user."
+    },
+    {
+      "name": "photos_list_albums",
+      "description": "List all photo albums in Proton Photos."
+    },
+    {
+      "name": "photos_create_album",
+      "description": "Create a new empty photo album in Proton Photos."
+    },
+    {
+      "name": "photos_delete_album",
+      "description": "Delete a Proton Photos album."
+    },
+    {
+      "name": "photos_list_album_photos",
+      "description": "List the photos in a Proton Photos album."
+    },
+    {
+      "name": "photos_add_to_album",
+      "description": "Add a photo from your Proton Photos library to an album."
+    },
+    {
+      "name": "photos_remove_from_album",
+      "description": "Remove a photo from a Proton Photos album."
     }
   ]
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "proton-drive-mcp",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "MCP server and CLI that gives Claude full access to Proton Drive — upload, download, share, and manage your end-to-end encrypted files without leaving the conversation.",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
+    "./services/drive": "./dist/services/drive.js",
     "./package.json": "./package.json"
   },
   "bin": {

package/smithery.yaml

@@ -35,6 +35,12 @@ tools:
   - drive_invitation_accept
   - drive_invitation_reject
   - drive_share_leave
+  - photos_list_albums
+  - photos_create_album
+  - photos_delete_album
+  - photos_list_album_photos
+  - photos_add_to_album
+  - photos_remove_from_album
 startCommand:
   type: stdio
   configSchema: