{
  "markdown": "# Apple-MCPs\n\n![CI](https://github.com/JonathanRReed/Apple-MCPs/actions/workflows/ci.yml/badge.svg)\n![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)\n![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)\n\nMCP servers that let an AI client use Apple apps and macOS tools. Create reminders, send messages, check calendars, search mail, manage files, and get directions.\n\nThe servers run on your Mac. Your MCP client may send returned data to its model provider, and Apple apps may sync through iCloud or another account. Local execution does not mean the data stays local.\n\nRequires Python 3.11+ and macOS. Uses MCP specification `2026-07-28` and Python SDK 2.x, with support for older client protocol revisions. [MIT license](LICENSE).\n\n## Install\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/), then register the unified server with your client.\n\nClaude Code:\n\n```bash\nclaude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp\n```\n\nCodex:\n\n```bash\ncodex mcp add apple-tools -- uvx apple-tools-mcp\n```\n\nOther stdio clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-tools\": {\n      \"command\": \"uvx\",\n      \"args\": [\"apple-tools-mcp\"]\n    }\n  }\n}\n```\n\nRun `uvx apple-tools-mcp` to start the server directly. Standalone servers use the same approach, such as `uvx apple-mcp-mail` or `uvx apple-calendar-mcp`.\n\nRestart your client after installing or upgrading. Call `search_tools` with `calendar health` to check discovery without reading app data.\n\nFor Claude Desktop, download a server's `.mcpb` bundle from [Releases](https://github.com/JonathanRReed/Apple-MCPs/releases) and double-click it.\n\nSet app-specific safety modes and directories in your client's `env` settings. The [configuration guide](Apple-Tools-MCP/README.md) lists defaults and options. Mail attachments are disabled until you set `APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT` to a dedicated directory. Files tools only access `APPLE_FILES_MCP_ALLOWED_ROOTS`; macOS may impose further restrictions.\n\n## Choose a server\n\nStart with [Apple-Tools-MCP](Apple-Tools-MCP/README.md). It combines all ten apps and tools below, plus saved defaults, contact routing, Mail thread helpers, undo, briefings, and cross-app workflows.\n\nChoose a standalone server to expose fewer apps to your client:\n\n| Server | macOS access | Health tool | Permission help |\n| --- | --- | --- | --- |\n| [Mail](AppleMail-MCP/README.md) | Automation access to Mail | `mail_health` | `mail_permission_guide`, `mail_recheck_permissions` |\n| [Calendar](Apple-Calendar-MCP/README.md) | Calendar access | `calendar_health` | `calendar_permission_guide`, `calendar_recheck_permissions` |\n| [Reminders](AppleReminders-MCP/README.md) | Reminders access | `reminders_health` | `reminders_permission_guide`, `reminders_recheck_permissions` |\n| [Messages](AppleMessages-MCP/README.md) | Automation; Full Disk Access for history | `messages_health` | `messages_permission_guide`, `messages_recheck_permissions` |\n| [Contacts](AppleContacts-MCP/README.md) | Contacts access | `contacts_health` | `contacts_permission_guide`, `contacts_recheck_permissions` |\n| [Notes](AppleNotes-MCP/README.md) | Automation access to Notes | `notes_health` | `notes_permission_guide`, `notes_recheck_permissions` |\n| [Shortcuts](AppleShortcuts-MCP/README.md) | Usually no separate prompt | `shortcuts_health` | `shortcuts_permission_guide`, `shortcuts_refresh_state` |\n| [Files](AppleFiles-MCP/README.md) | Allowed roots and protected-folder access | `files_health` | `files_permission_guide` |\n| [System](AppleSystem-MCP/README.md) | Some actions need System Events, Accessibility, or Automation | `system_health` | `system_permission_guide` |\n| [Maps](AppleMaps-MCP/README.md) | No privacy prompt; Swift helper needs Xcode command line tools | `maps_health` | `maps_permission_guide` |\n\nThe unified server uses `apple_health`, `apple_permission_guide`, and `apple_recheck_permissions`. You must approve permissions yourself in the macOS prompt or System Settings.\n\n## Find and use tools\n\nMCP `tools/list` returns each tool's schemas and read or write annotations. Use `search_tools` to search names, descriptions, and aliases; use `get_tool_info` for one tool's schema and examples.\n\nResolve recipients through Contacts before sending, unless you have the exact address. For Mail conversations, use `mail_get_thread`, `mail_reply_latest_in_thread`, or `mail_archive_thread`. Pass an exact sender email in `from_account` when the sending identity matters.\n\nMail search requires a query: a sender, subject fragment, or `*`. Reminders `due_date` requires a timezone offset, such as `yyyy-MM-ddTHH:mm:ss-08:00`. Omit `service_name` when sending iMessages.\n\nThe unified server also provides `apple_generate_daily_briefing`, `apple_generate_weekly_briefing`, and `apple_triage_communications_task`. Clients without prompt support can use `apple_list_prompts`, `apple_get_prompt`, and their per-server equivalents.\n\nFor calls from Python, use the metadata in `generated/tool_catalogs/` and wrappers in `generated/tool_wrappers/python/`. See [code-mode.md](docs/code-mode.md).\n\n## Transport and stored state\n\n`stdio` is the default. To use Streamable HTTP, set `APPLE_<DOMAIN>_MCP_TRANSPORT=streamable-http` and the matching `_HOST` and `_PORT` variables.\n\nHTTP must bind to `127.0.0.1`, `::1`, or `localhost`. The servers have no remote authentication and reject network and wildcard binds. Do not expose them through a tunnel or public proxy.\n\nApple-Tools-MCP stores defaults in `~/.apple-tools-mcp/preferences.json`, configurable through `APPLE_AGENT_MCP_STATE_FILE`. It stores recent actions in `~/.apple-tools-mcp/actions.json` for audit and undo.\n\n## Develop\n\n```bash\ngit clone https://github.com/JonathanRReed/Apple-MCPs.git\ncd Apple-MCPs\nuv sync --all-packages\n```\n\nThe uv workspace installs every server into `.venv/bin`. Each server folder also has a `start.sh` for clients; it uses uv when available and otherwise creates a virtual environment. Root `pyproject.toml` defines workspace members, and `uv.lock` pins dependencies.\n\n| Path | Contents |\n| --- | --- |\n| `Apple-Tools-MCP/` | Unified server; module `apple_agent_mcp`, environment prefix `APPLE_AGENT_MCP_*` |\n| `Apple<Domain>-MCP/` | Standalone servers; Calendar uses `Apple-Calendar-MCP` |\n| `AppleMCPCommon/` | Shared discovery and search, published as `apple-mcp-common` |\n| `generated/` | Tool catalogs and Python wrappers |\n| `scripts/` | Installation, checks, generation, and bundle builds |\n| `docs/` | Project and launch documentation |\n\nRun smoke checks:\n\n```bash\nbash scripts/inspector_smoke.sh\nuv run python scripts/protocol_smoke.py\n```\n\nFor the official conformance suite, start the server in a separate terminal:\n\n```bash\nAPPLE_AGENT_MCP_TRANSPORT=streamable-http \\\nAPPLE_AGENT_MCP_PORT=8765 \\\nAPPLE_AGENT_MCP_CONFORMANCE_MODE=1 \\\n./Apple-Tools-MCP/start.sh\n```\n\n```bash\nnpx -y @modelcontextprotocol/conformance@0.2.0-alpha.11 server --url http://127.0.0.1:8765/mcp --requirements 2026-07-28\n```\n\nConformance mode registers test fixtures. Use it only for protocol validation. [CI](.github/workflows) runs lint, macOS and Linux tests, generated-file checks, Inspector smoke checks, and conformance tests.\n\n## Documentation\n\n[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Troubleshooting](docs/troubleshooting.md) · [MCP compatibility](docs/mcp-compatibility.md) · [Publishing](docs/publishing.md) · [Changelog](CHANGELOG.md) · [Trademark notice](NOTICE.md) · [Launch docs](docs/launch/)\n",
  "bytes": 7596,
  "sha": "a85033ba3af1ef8f033520fd3b5b643e81bb2db6942a8b81634d496731ed6fbe",
  "repo_slug": "jonathanrreed/apple-mcps",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jonathanrreed_apple_maps_mcp_f57bfd21/readme"
}