Apple2Agent
Integrates with Apple services on macOS, including calendars, mail, reminders, contacts, notes, and selected files. It supports finding free time and managing events, reading selected mail and preparing messages for approval before sending, and creating reminders with saved due dates and alarms.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Apple2Agent
Let AI agents work with your Apple Calendar, Mail, Reminders, Contacts, Notes and files — without handing them the keys.
A local MCP server for macOS. Your agent only sees the resources you pick, and nothing gets sent until you approve it on your Mac.
中文 · Quick start · How approval works · Compatibility · Privacy
Why Apple2Agent?
Giving an agent your inbox and calendar is useful right up until it emails the wrong person or deletes the wrong meeting. Apple2Agent is built around that risk:
You pick the exact resources. Choose which calendars, mail accounts, reminder lists, note folders and directories are exposed. Anything you didn't select stays out of the agent's reach.
Sending requires approval on your Mac. Outgoing mail is frozen and shown to you in a native macOS window. Only the exact content you approved can be sent. The agent has no tool that can approve its own actions.
Edits check what the agent last read. Updates and deletes carry the revision the agent read. If the item changed in the meantime, the write is rejected instead of silently overwriting your change.
Retries don't duplicate. Every write carries a stable
request_id. Retrying with the same ID returns the recorded result instead of creating a second event or a second email.Content is treated as data, not instructions. Tool descriptions and server instructions tell the model that mail bodies and event text are untrusted, which limits prompt injection through your own inbox.
Credentials stay in Keychain. You enter secrets in native setup windows, never in chat, config files or command arguments.
Related MCP server: Nico Apple MCP
What you can ask
Show my free 30-minute slots tomorrow afternoon. Don't change anything.
Summarize the three most recent emails in my work inbox and tell me which ones need a reply.
Draft a reply to the last message from Alice saying I can do Thursday, and queue it for my approval.
Remind me to submit the expense report on Friday at 10:00, in my "Work" list.
Which contacts have birthdays in the next two weeks?
Modules
Module | What the agent can do |
📅 Calendar | List, search, create, update and delete events (including recurring ones), find free time, check conflicts |
Search, read, threads, drafts, approved send/reply/forward, move/mark, bulk actions with undo | |
⏰ Reminders | Lists, tasks, due dates, repeats, alarms, completion |
👤 Contacts | Search, birthdays, groups, create/update/delete (CardDAV) |
📝 Notes | Read, create, append, move, delete with backups |
📁 Files | Scoped folders, text extraction, conditional writes, trash |
💬 Messages | Read selected chats and incoming unread SMS, approved iMessage sending |
See the compatibility matrix for per-module verification and limits.
Quick start
Let your agent install it
Paste this into Claude Code, Cursor, Codex or any coding agent that can run shell commands on your Mac:
Install Apple2Agent (https://github.com/AndreLYL/Apple2Agent) on this Mac and connect it to this MCP client. Follow these rules:
1. Check prerequisites: macOS, Node.js 24 or newer, Python 3, Git and Xcode Command Line Tools. If anything is missing, tell me how to install it and stop.
2. If ~/.local/bin/apple2agent already exists, stop and ask me first. Reinstalling switches the active release.
3. Clone the repository into ~/Apple2Agent (or a folder I name), then run inside it:
npm ci
APPLE2AGENT_SIGN_IDENTITY=- npm run build
npm run install:local
4. Do not run setup yourself and never ask me for passwords in chat. Tell me to run ~/.local/bin/apple2agent setup in my own terminal, and wait until I confirm it is done.
5. Add an MCP server named "apple2agent" to this client's configuration. Use the launcher's absolute path (expand $HOME, no ~) with args ["serve", "--profile", "readonly"].
6. Tell me to restart or reconnect the client. After that, verify the connection by listing my calendars.Setup opens native macOS windows where you enter your account yourself, so the agent never sees your password. For iCloud, have an app-specific password ready.
Or install manually
1. Prerequisites
A Mac with Node.js 24+, Python 3, Git and Xcode Command Line Tools (
xcode-select --install)For iCloud Calendar and Contacts: an app-specific password for your Apple Account (not your main password)
2. Build and install
git clone https://github.com/AndreLYL/Apple2Agent.git
cd Apple2Agent
npm ci
APPLE2AGENT_SIGN_IDENTITY=- npm run build
npm run install:localAPPLE2AGENT_SIGN_IDENTITY=- signs the native helpers ad hoc, so no developer certificate is needed. The installer puts the launcher at ~/.local/bin/apple2agent and keeps the previous release for rollback. It doesn't install any background service.
Already running Apple2Agent? Read upgrade and rollback before reinstalling.
3. Connect your accounts
~/.local/bin/apple2agent setupNative windows walk you through entering your account and choosing the calendars to expose. Add more modules only when you need them:
~/.local/bin/apple2agent configure reminders # also: mail, contacts, notes, drive4. Add it to your MCP client
Most clients don't expand ~, so use the absolute path. Print it with:
echo "$HOME/.local/bin/apple2agent"Start with the readonly profile. You can switch to a write-enabled profile once you trust the setup.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"apple2agent": {
"command": "/absolute/path/to/apple2agent",
"args": ["serve", "--profile", "readonly"]
}
}
}claude mcp add apple2agent -- "$HOME/.local/bin/apple2agent" serve --profile readonlyEdit ~/.cursor/mcp.json:
{
"mcpServers": {
"apple2agent": {
"command": "/absolute/path/to/apple2agent",
"args": ["serve", "--profile", "readonly"]
}
}
}Edit ~/.codex/config.toml:
[mcp_servers.apple2agent]
command = "/absolute/path/to/apple2agent"
args = ["serve", "--profile", "readonly"]Restart the client, then try: "List my calendars."
Profiles
A profile limits which tools the agent can see. Your resource selections still apply on top of it.
Profile | Tools (all modules enabled) | Use it for |
| 45 | First run and everyday lookups. No writes of any kind. |
| 9 | Scheduling assistants. Includes calendar writes to calendars you authorized. |
| 92 | Full access to every module you enabled. |
Fewer enabled modules means fewer tools. Smaller tool lists also help the model pick the right tool.
How sending is approved
The agent can prepare an email, but it can't send one on its own:
sequenceDiagram
participant Agent as AI agent
participant A2A as Apple2Agent (your Mac)
participant You
participant Mail as Mail server
Agent->>A2A: mail_send_message(...)
A2A-->>Agent: queued_for_approval + action_id
You->>A2A: apple2agent review ACTION_ID
A2A->>You: Native window shows the frozen message
You->>A2A: Allow once
Agent->>A2A: mail_execute_send(action_id)
A2A->>Mail: Sends exactly what you approvedIf the draft, recipients or sender change after you review it, execution is refused and the agent has to prepare a new action.
Privacy at a glance
Runs locally over stdio. There's no shared backend, telemetry or hosted service.
Credentials are stored in Apple2Agent's own Keychain items. Private state lives in
~/Library/Application Support/Apple2Agent, outside the source checkout.Tool results go to your agent client. If that client uses a cloud model, the content you ask about leaves your Mac through it. Running locally doesn't change that.
Details: data flow and permissions.
Remote access (optional)
You can expose your local server to ChatGPT through your own OpenAI Secure MCP Tunnel. Your Mac has to be online, and final send approval still happens on the Mac.
Known limitations
This is a source alpha. In particular:
macOS only. Tested on Apple Silicon; the minimum macOS version and Intel support aren't established yet.
No prebuilt or notarized binary yet. You install from source.
Approval happens in a terminal-launched native window (
apple2agent review). Mobile-only approval isn't implemented.The native setup and approval windows are currently in Simplified Chinese.
The independent IMAP/SMTP adapter needs an app password. OAuth-only mail providers aren't supported yet.
Documentation
Getting started: install, upgrade, rollback, uninstall
Compatibility: what's verified, what's pending
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for the development checks (npm run typecheck, npm test, npm run check:privacy) and SECURITY.md for reporting vulnerabilities.
If Apple2Agent is useful to you, a ⭐ helps other people find it.
License
MIT. Third-party code keeps its own licenses; see THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Mail, Calendar, Messages, Notes, Contacts, Slack on your Mac for AI. Remote needs Pro or free trial.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI to control Apple Mac apps like Messages, Notes, Contacts, Mail, Reminders, Calendar, and Maps through natural language commands.MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to interact with local Apple Calendar, Notes, and Contacts on macOS. Provides tools for creating, reading, updating, and deleting events, notes, and contacts through natural language.MIT
- AlicenseNot gradedqualityBmaintenanceExposes 28 native tools that let an agent list, search, create, complete and delete Apple Calendar events and reminders, read and compose Mail drafts, inspect and script Safari tabs, and take full-screen, window, region or clipboard screenshots. All actions run through host AppleScript and EventKit with confirmation gates on deletes and never send mail automatically.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to call native macOS calendars, reminders, files, desktop/system actions, selected Apple apps, shortcuts, and web tools through MCP, with scoped file access and explicit approvals for writes.63MIT