PyiCloud

This repository adds an iCloud Photos MCP server for direct cloud access, without a local Apple Photos library. Reads work by default; explicitly enabled organizing tools create, rename, move and delete containers, edit photo metadata, and manage photo memberships. Library photo deletion needs a separate opt-in. Install with uv pip install ".[cli,mcp]", authenticate separately, then run icloud-photos-mcp. See the Photos MCP setup and tool guide for session setup, client configuration, privacy boundaries, pagination, and search limitations. For Docker and Unraid, see the Unraid installation guide.

PyiCloud is a module which allows pythonistas to interact with iCloud webservices. It's powered by the fantastic requests HTTP library.

At its core, PyiCloud connects to the iCloud web application using your username and password, then performs regular queries against its API.

Please see the terms of use for your responsibilities when using this library.

For support and discussions, join our Discord community: Join our Discord community

Installation

Install the library and CLI with:

$ pip install "pyicloud[cli]"

This installs the icloud command line interface alongside the Python package. To install the library on its own run pip without the cli extra.

$ pip install pyicloud

Related MCP server: icloud-mail-calendar-contacts-mcp

Authentication

Authentication without using a saved password is as simple as passing your username and password to the PyiCloudService class:

from pyicloud import PyiCloudService

api = PyiCloudService("jappleseed@apple.com", "password")

In the event that the username/password combination is invalid, a PyiCloudFailedLoginException exception is thrown.

For China mainland accounts, long-running daemon settings, family polling, pause_2fa, and the full two-step / two-factor (2SA/2FA) flow, see the Authentication guide. The icloud CLI can also store your password in the system keyring; see the Command-Line Interface guide.

Documentation

Full documentation lives under docs/. It is also published, with a generated API reference, at pyicloud.readthedocs.io.

Guides

• Authentication — login, pause_2fa, and 2SA/2FA

• Command-Line Interface — the icloud command, auth/session management, and keyring storage

• Diagnostics — icloud doctor and its exit codes

Services

• Account — account info, storage, and summary plan

• Devices & Find My — list devices and locate, ring, lock, or erase them

• Calendar — calendars, events, alarms, and invitees

• Contacts — the address book and MeCard

• File Storage (Drive) — iCloud Drive and the legacy Ubiquity API

• Photos — browse, sync, upload, and modify the photo library

• Hide My Email — generate and manage email aliases

• Mail — experimental folder and message reads, verified sender identities, bounded single-/multi-folder searches, previews, Unread/Flagged thread filters, cursor enumeration of filtered thread identities (icloud mail filter-threads), private JSON and original MIME/EML export (icloud mail export-eml), restricted size-bounded Mail Drop downloads (icloud mail download-maildrop), exact message lookup (icloud mail get by ID or UID), opt-in mailbox/thread/flag-filter UID enumeration, folder-scoped thread expansion, bodies, attachment streams, and one-shot POSIX metadata inventory synchronization (icloud mail sync), also available through icloud mail; plus separate explicit single-message read/unread and flag/unflag writes and ordinary mailbox moves through set_read(), set_flagged(), move(), and icloud mail mark / icloud mail move, plus guarded draft saves/discard with recipients and ordinary attachment uploads and folder creation, renaming, and confirmed irreversible deletion through the library and CLI, plus explicit reply/forward drafts and confirmed sending and confirmed single-message permanent deletion from Trash

• Reminders — lists, reminders, alarms, tags, and attachments

• Notes — folders, note rendering, and HTML export

• Invites — read events and respond to invitations

Examples

If you want to see some code samples, see the examples.

Contributing

Contributions are welcome! Please read the Contributing guide, the Code of Conduct, and the Terms of Use before getting started.

To report a security vulnerability, use private vulnerability reporting rather than opening a public issue (see SECURITY.md).