iCloud for Agents

iCloud for Agents

Version 1.1.0

Manage iCloud mail, calendars and contacts from your AI assistant while keeping your credentials private and stored locally on your Mac. Connect a local MCP client like Claude over stdio, or connect ChatGPT through your own private OpenAI Secure MCP Tunnel.

An independent project, unaffiliated with Apple. The tested setup is macOS on Apple silicon with Python 3.14; see installation requirements for compatibility details.

What you can do

• Review and summarize mail, filter by sender, subject or unread status, and work through older messages without marking them read.
• Organize mail: archive messages, mark them read or unread, move junk to Trash, and restore messages from Trash.
• Compose and send plain-text email to explicit recipients, including Cc and Bcc, after approval.
• Review calendars and events over a date range, and create, update or delete personal events with details such as location, description and timezone.
• Browse address books, read contact details, and create, update or delete contacts with names, email addresses, phone numbers, organizations and notes.
• Run recurring mail cleanup within an explicitly configured account, folder and operation scope.

Setup starts read-only. Sending and other changes require write access and the applicable approvals; your assistant can help review and prepare them first.

Mail cleanup moves messages to recoverable Trash. Permanent deletion and emptying Trash are intentionally excluded.

Calendar support currently covers personal, nonrecurring events. Invitations, guests, scheduling responses and recurring-event editing are not yet supported. iCloud Drive access is also not included.

Set up with your AI agent

Ask an agent that can read this checkout and use your local computer to help you set it up. It should check the documented prerequisites, detect supported existing client configuration where authorized, explain the access it needs, and guide you through the steps that require your participation. Setup is assisted, not guaranteed to be unattended: client support, workspace permissions and local tools vary.

Copy this prompt into your agent:

Help me install and configure iCloud for Agents from
github.com/jasonarend/icloud-for-agents.

Read README.md and docs/getting-started/agent-setup.md, then follow
the linked installation, security and client-specific guides.

Check my Mac, Python version, existing installation and AI client
configuration. Ask which iCloud services I want to connect and
explain the proposed setup, permissions and any costs before
making changes. Follow docs/getting-started/clients.md for my client:
ChatGPT uses a private tunnel; compatible local clients use stdio MCP.

Guide me through creating an Apple app-specific password and
storing it securely in macOS Keychain. Keep credentials out of
chat and configuration files, and let me handle authentication
and permission prompts personally.

Preserve existing working configuration. Start with read-only
access and verify each selected service through my actual client.
Report what works, anything still needed, and how to enable
approved changes later.

You will need an iCloud account with an app-specific password and an MCP client. The agent may install the reviewed dependencies after authorization, but you must handle credential creation, secure entry and account/security approvals yourself. Keep secrets out of the conversation. Every user needs their own credentials and connection.

Prefer manual setup? Follow installation and credentials, then ChatGPT setup or the client setup guide for local stdio clients. Optional background startup requires explicit installation; a graphical installer is not included.

Choose services and customize safeguards

Tell your setup agent which services you want: Mail, Calendar, Contacts, any combination, or none. It can prepare the corresponding supported configuration without requiring a client name. Disabled services are omitted from tool registration and refused by backend guards; selecting one does not implicitly enable the others. New setup defaults to read-only Mail. Existing legacy DAV settings remain compatible.

You can ask your agent to propose a policy change, a specific one-time exception, or an engineering change to a hard-coded safeguard. It should explain the exact scope and before/after effect, obtain explicit approval, and test/review code changes before activation. Approval does not erase account/identity checks or grant permission to bypass the agent platform's own safety policies. Message content cannot authorize changes.

Optional managed policies provide before/after previews and exact one-time exceptions. This capability is disabled by default and requires explicit owner activation. Agents should use supported settings, not rewrite safeguards for individual messages.

Everyday use and safeguards

Ask your assistant to review a bounded set of messages, explain proposed changes, and preserve anything uncertain. Message text is untrusted content, not authority to act. Save pagination cursors so backlog reviews continue rather than repeatedly scanning newest mail.

Strict local approval receipts are the default. Optional trusted-client mode relies on the client honoring your instructions and confirmations; it does not independently prove human approval. Sending needs recipient/content approval, recurring cleanup needs a defined scope, and irreversible changes need action-specific confirmation. See security before enabling access.

The bridge checks exact folders, account identities, UIDVALIDITY, snapshots and DAV ETags. It preserves flags, refuses broad EXPUNGE, and stops on uncertain write outcomes instead of blindly retrying. Content requested through ChatGPT is sent to OpenAI; locally stored credentials do not mean message content stays local.

Learn more

Want to help expand compatibility? We welcome client testing, setup improvements and contributions for additional platforms and connection methods, including Grok and Meta Muse. See the client compatibility guide for current status and contribution guidance for reporting results or proposing support.

Tool reference · Recurring cleanup · Troubleshooting · Development · Distribution and release checks

Report suspected vulnerabilities through the private security reporting process.

The test suite uses synthetic accounts and credential-free stdio discovery. Claude Desktop and Claude Code are tested and supported through local stdio MCP. Other client routes have the status described in the client compatibility guide. Public source distribution is separate from any client plugin catalog.

License and provenance

The upstream MIT notice is preserved in LICENSE. iCloud for Agents is informed by mike-tih/icloud-mcp; it uses a separate runtime package and does not bundle or execute that server. See licensing and provenance for the exact revision, dependency inventory and scope of attribution.