Provides access to iCloud Mail and Calendar, enabling email search, reading, drafting, sending reviewed drafts, marking read/unread, moving messages, and calendar management including listing calendars, finding events, and creating, editing, or deleting personal events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@icloud-agent What's on my calendar for tomorrow?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read and send iCloud email, draft replies, and manage your calendar from Codex or another local AI agent.
Connect once and choose which sender addresses and calendars your agent can use.
“Show me the unread emails I received today.”
“Find Alex's email about the invoice and draft a reply.”
“Send that draft from my work address.”
“What's on my calendar tomorrow?”
“Add lunch with Alex at noon on Thursday to my Personal calendar.”
What you can do | Current limits | |
Search by text, sender, subject, date, or unread status; read messages; draft and send; mark read/unread; archive or move messages | One account; plain-text drafts; attachment metadata only | |
Calendar | Check your schedule, find recurring occurrences, draft events for review, then confirm creation; edit or delete personal events in enabled calendars | No recurrence editing, invitations, or RSVP management |
Reading preserves each message's read/unread status. Drafts are saved until you send them. Calendar drafts stay local until you review and confirm them.
Related MCP server: local-apple-mcp
You need iCloud Mail and Calendar, and an agent that can run a local command or MCP process on your computer.
Client | Integration |
Codex locally |
|
Other local agents | Use the companion skill and CLI, or run |
ChatGPT desktop local work | Plugin included; client/account compatibility is unverified |
ChatGPT web, cloud, mobile | Not supported |
Your computer needs to be awake, online, and able to unlock its credential store. Agent and plugin setup →
Live calendar writes and recipient delivery remain unverified. Verification record →
Install with Homebrew on macOS:
brew install MarkUnthank/tap/icloud-agent
icloud-agent setup --codex
icloud-agent auth loginYou need an iCloud Mail account, Apple Account two-factor authentication, and Codex
on PATH for setup --codex.
Generate an app-specific password when login opens Apple's sign-in page, then paste it into the terminal's masked prompt.
Choose sender addresses and calendars with Space and Enter. Your default sender can be an alias. Confirm or edit the Sender name recipients will see.
Once connected, choose Install agent skills or Finish. If installing, select any additional agents, or press Enter with none selected to install just the shared skill. Restart your agent after setup.
Change your account settings with icloud-agent auth configure; install or update
skills with icloud-agent setup --skills.
Or use the CLI directly:
icloud-agent mail search
icloud-agent calendar list
icloud-agent schema mail_draftSee setup for uv/pipx installation, upgrades, and removal.
Credentials live in macOS Keychain, Windows Credential Manager, or Linux Secret Service.
The connector talks directly to Apple, with no intermediary server or telemetry.
Account addresses, calendar drafts, and write-attempt records are stored locally; inbox bodies are not cached.
Mail and calendar data returned to an AI client enter that client's context.
Read security and privacy, or report a vulnerability privately.
Guide | What's inside |
Install, authenticate, upgrade, switch accounts, uninstall | |
Copyable mail/calendar workflows and JSON output | |
Every operation, input, default, and constraint | |
Codex, generic MCP clients, skill, desktop plugin | |
Login, keychain, PATH, conflicts, uncertain sends | |
How the CLI, MCP, protocols, and state fit together | |
What has been tested and what remains unverified |
Bug reports, improvements, and live compatibility results are welcome. Start with CONTRIBUTING.md, community conduct, or the support guide.
Maintained by Mark Unthank. Changelog →
MIT, including the source, skill, and project artwork. Dependencies retain their own licenses.
Independent project; not affiliated with Apple or OpenAI. iCloud is a trademark of Apple Inc.
This server cannot be deployed
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
