Metadata-Version: 2.4
Name: apple-tools-mcp
Version: 1.0.2
Summary: Unified Apple ecosystem MCP server for macOS
License-Expression: MIT
Project-URL: Homepage, https://github.com/JonathanRReed/Apple-MCPs
Project-URL: Repository, https://github.com/JonathanRReed/Apple-MCPs
Project-URL: Changelog, https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/JonathanRReed/Apple-MCPs/issues
Keywords: mcp,model-context-protocol,macos,apple,ai-agent,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apple-mcp-common<2,>=1.0.0
Requires-Dist: apple-calendar-mcp<2,>=1.0.0
Requires-Dist: apple-contacts-mcp<2,>=1.0.0
Requires-Dist: apple-files-mcp<2,>=1.0.0
Requires-Dist: apple-mcp-mail<2,>=1.0.0
Requires-Dist: apple-maps-mcp<2,>=1.0.0
Requires-Dist: apple-messages-mcp<2,>=1.0.0
Requires-Dist: apple-mcp-notes<2,>=1.0.0
Requires-Dist: apple-mcp-reminders<2,>=1.0.0
Requires-Dist: apple-shortcuts-mcp<2,>=1.0.0
Requires-Dist: apple-system-mcp<2,>=1.0.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: pydantic>=2.12.0
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

<!-- mcp-name: io.github.JonathanRReed/apple-tools-mcp -->

# Apple-Tools-MCP

Unified MCP server for Apple apps on macOS.

One entrypoint for Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps. This server wraps the standalone servers and exposes a unified MCP interface.

## What It Does

- Read context across multiple Apple apps
- Unified actions across all apps
- Prompts for day planning, communications triage, and meeting prep
- Persistent defaults for mail, calendar, reminders, notes, and communication routing
- Per-contact preferences for people who always route a specific way
- Helper workflows for communication routing, archiving mail, capturing follow-ups, and collaboration summaries
- Mail thread helpers and Contacts method editing in one place
- Preview, audit, and undo for reversible actions
- Files-aware attachment and document workflows within scoped roots
- System-aware workflows using the frontmost app, clipboard, notifications, running apps, and assistant-relevant macOS settings
- Truthful Focus context and combined system snapshots for briefing and routing
- Explicit macOS settings writes for appearance, Finder, Dock, and key accessibility preferences
- Bounded GUI fallback tools when a native app-domain MCP cannot complete a task directly
- Finder-aware file workflows, Finder tags, recent locations, and iCloud Drive awareness through Apple Files
- Travel-aware workflows using Apple Maps for place search and route estimates
- Daily briefing, weekly briefing, and communications-triage tools
- Prompt fallback via `apple_list_prompts` and `apple_get_prompt`
- One install target instead of ten separate configurations

## When to use

- Personal assistant workflows across multiple Apple apps
- Cross-app operations (e.g., Calendar and Reminders together)
- Simpler setup without wiring each standalone MCP separately

## Tool Discovery

Apple-Tools-MCP exposes its full tool surface through `tools/list`, with `readOnlyHint`/`destructiveHint` annotations and structured output schemas — modern clients defer-load large tool surfaces themselves. For context-constrained clients:

- `search_tools` finds tools by name, aliases, and domain tags
- `get_tool_info` loads the full schema and examples for one tool on demand
- generated code-mode wrappers are exported under `generated/tool_wrappers/python`

## Install On This Mac

<details>
<summary>Quick start (uvx, from PyPI)</summary>

With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:

```bash
uvx apple-tools-mcp
```

No clone, no venv management.

</details>

<details>
<summary>From a clone</summary>

```bash
git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages
```

This builds one uv workspace environment with the unified entrypoint at `.venv/bin/apple-tools-mcp` plus every standalone server's console script (`bash scripts/install_all.sh` does the same, with a venv fallback for machines without uv). You can also point an MCP client at `Apple-Tools-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).

</details>

## Install In AI Agents

<details>
<summary>Generic MCP client config</summary>

```json
{
  "mcpServers": {
    "apple-tools": {
      "command": "uvx",
      "args": ["apple-tools-mcp"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "full_access",
        "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
        "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_NOTES_MCP_SAFETY_MODE": "full_access",
        "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access",
        "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access"
      }
    }
  }
}
```

Running from a clone instead? Use `/path/to/Apple-MCPs/Apple-Tools-MCP/start.sh` as the command with empty `args`.

</details>

<details>
<summary>Claude Code example</summary>

```bash
claude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp
```

</details>

## What It Exposes

- Health and overview tools across all apps
- Cross-app prompts
- Delegated tools from Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps
- Suggestions and permission guides
- Files, System, and Maps resources and prompts
- Unified wrappers for Focus, system context, Finder reveal, file open, and file tagging
- Preference tools: get, detect, and update defaults and contact preferences
- Communication tools: prepare, send, preview
- Workflow tools: archive, create reminders and notes with defaults, preview those defaulted writes, capture follow-ups, preview follow-up capture, and summarize event collaboration
- Launch-hardening tools: strict Maps wrappers, duplicate-contact detection, digest-folder helpers, and Shortcut bridge routing
- Audit tools: list recent actions and undo
- Briefing tools: daily, weekly, and communications triage
- Prompt fallback: `apple_list_prompts` and `apple_get_prompt`
- Mail thread tools: get, reply, archive
- Contacts mutation: create, update, delete with labeled methods
- Calendar and Messages permission diagnostics
- Launch and recovery: `apple_health`, `apple_permission_guide`, `apple_recheck_permissions`

## Assistant Defaults

Apple-Tools-MCP can persist a lightweight assistant state file with defaults for:

- default mail account
- default archive mailbox
- default calendar
- default reminders list
- default notes folder
- preferred communication channel, `messages`, `mail`, or `auto`
- preferred message target type, `phone`, `email`, or `auto`
- per-contact preferred channel and target overrides for specific people

Detect and persist sensible defaults with `apple_detect_defaults`, inspect them with `apple_get_preferences`, and override them with `apple_update_preferences`.

By default the state file is stored at `~/.apple-tools-mcp/preferences.json`. Override it with `APPLE_AGENT_MCP_STATE_FILE`.

Apple-Tools-MCP also stores recent assistant actions in `~/.apple-tools-mcp/actions.json` so the unified server can expose audit history and undo for reversible operations.

## How to Work With It

- Resolve people through Contacts first, then decide between Messages or Mail based on saved defaults.
- Set per-contact preferences for people who always prefer a specific channel.
- Preview risky actions and defaulted create flows when the client wants confirmation.
- Use Mail thread helpers when the user refers to a conversation, not a single message.
- Set defaults early (archive mailbox, calendar, reminders list, notes folder) so the assistant doesn't keep asking.
- Keep contact info current so communication routing works reliably.
- Use Files before Mail, Messages, Notes, or Shortcuts when the request involves local documents.
- Check System context before interruptive actions, especially when the frontmost app, clipboard, or battery state matters.
- Treat Focus support as truthful best-effort. Use it when available, and do not invent a current Focus mode if the MCP reports unsupported on the local setup.
- Use `apple_update_system_setting` for macOS preference changes and `apple_control_frontmost_app` only when a native app-domain tool cannot complete the task.
- Prefer explicit System settings tools over generic GUI automation when the request is really a macOS preference change.
- Use GUI fallback tools only when the native domain MCP cannot complete the task and the client has granted Accessibility access.
- Use native Maps MCP tools for maps search and directions. Do not substitute shell, web, or external map providers when validating supported Maps behavior.
- Use Shortcuts as the explicit bridge when native domain support is missing, rather than ad hoc shell or GUI work.
- Use the dedicated digest folder helpers before saving daily or weekly briefings into Notes.
- Use Maps when routing or travel time affects scheduling or communication.
- Use `apple_list_recent_actions` and `apple_undo_action` for reversible operations.
- When Mail must use a specific sender identity, pass the exact sender email in `from_account`, not just an account nickname.

## macOS Permissions

- Mail needs Automation access to Mail
- Calendar needs Calendar access
- Reminders needs Reminders access
- Messages needs Automation access to Messages, plus Full Disk Access for history
- Contacts needs Contacts access
- Notes needs Automation access to Notes
- Shortcuts usually works without a separate privacy prompt
- Files access is controlled by `APPLE_FILES_MCP_ALLOWED_ROOTS`, not by a macOS privacy prompt
- System actions may trigger System Events, Accessibility, or automation prompts depending on the host app
- Focus status is best-effort and truthful on unsigned local installs
- Notification Center history is not claimed where macOS does not expose it cleanly
- Maps does not need a privacy prompt, but search and directions require the local Swift helper to compile

## Launch Checklist

- Add `uvx apple-tools-mcp` (or a clone's `Apple-Tools-MCP/start.sh` / installed `.venv/bin/apple-tools-mcp` entrypoint) to your MCP client
- Reload or reconnect the client so the Apple-Tools-MCP tool surface is loaded into context
- Call `apple_health` first to verify every domain
- If a domain is blocked, call `apple_permission_guide`
- After changing macOS permissions, call `apple_recheck_permissions`

## Transports and Protocol Verification

`stdio` is the default and recommended transport. Set `APPLE_AGENT_MCP_TRANSPORT=streamable-http` (with optional `APPLE_AGENT_MCP_HOST` and `APPLE_AGENT_MCP_PORT`) to serve Streamable HTTP instead — used below for protocol validation.

### Official MCP conformance

Start Apple-Tools-MCP in conformance mode:

```bash
cd /path/to/Apple-MCPs/Apple-Tools-MCP
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./start.sh
```

Then run the official active suite:

```bash
npx -y @modelcontextprotocol/conformance server \
  --url http://127.0.0.1:8765/mcp \
  --suite active
```

`APPLE_AGENT_MCP_CONFORMANCE_MODE=1` adds an opt-in MCP conformance surface covering content types, resources, resource templates, prompts, progress, and completion (fixtures for features removed by spec 2026-07-28 are intentionally absent). It is intended for CI and protocol testing, not normal assistant use.

The briefing and triage tools (`apple_generate_daily_briefing`, `apple_generate_weekly_briefing`, `apple_triage_communications_task`) are standard synchronous tools — the experimental MCP tasks API they previously used was removed from the spec (SEP-1686) and SDK, with the same tool names and results.

## Launch Docs

- [Golden Workflows](../docs/launch/golden-workflows.md)
- [Failure Modes](../docs/launch/failure-modes.md)
- [Compatibility and Version Pinning](../docs/launch/compatibility.md)
- [Code Mode](../docs/code-mode.md)
- [Demo Script](../docs/launch/demo-script.md)
- [Checklist Template Prompt](../docs/launch/prompts/checklist-template.md)

### Inspector CLI smoke check

From this server directory:

```bash
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method tools/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method prompts/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method resources/list
```

For the full repo-wide smoke pass, run:

```bash
cd /path/to/Apple-MCPs
bash scripts/inspector_smoke.sh
```

## Agent Routing Prompt

```xml
<apple_tools>
`tools/list` returns the full tool surface. If context is constrained, use `search_tools` first, then `get_tool_info` only for the tools you plan to call.

<routing>
  <imessage trigger="text, message, msg, iMessage">
    Resolve recipient via Contacts first. Confirm if multiple matches.
    Omit service_name parameter entirely.
  </imessage>

  <contacts trigger="lookup, phone number, email, contact">
    Run before any iMessage or Mail action.
  </contacts>

  <mail trigger="email, mail, inbox, draft, reply">
    Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
    If text vs. email is ambiguous, ask once.
  </mail>

  <calendar trigger="calendar, event, schedule, appointment, meeting, block time">
    Confirm date, time, duration, and title before writing.
  </calendar>

  <reminders trigger="remind me, task, to-do, don't forget">
    Reminders are organized into lists. Identify available lists on first use and set a default.
    due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00
  </reminders>

  <notes trigger="note, jot down, write this down, save this">
    Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
    Use for reference only. Time-sensitive items go to Reminders or Calendar.
  </notes>

  <shortcuts trigger="shortcut, automation, run shortcut">
    List available shortcuts before running if request is vague.
  </shortcuts>

  <files trigger="file, folder, attachment, document, download, desktop">
    Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
    Confirm the exact path before mutation or send actions.
  </files>

  <system trigger="clipboard, frontmost app, battery, notification, open app">
    Use System when local desktop context affects the next action.
    Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.
  </system>

  <maps trigger="map, directions, route, commute, eta, address, place">
    Use Maps when place lookup or travel time affects scheduling or communication.
    Confirm origin, destination, and transport mode for time-sensitive plans.
  </maps>
</routing>

<disambiguation>
  1. Has due date/time -> Reminders
  2. Reference material, no action -> Notes
  3. Involves another person -> iMessage or Mail (Contacts first)
  4. Text vs. email unclear -> ask once
</disambiguation>

<known_gotchas>
  - service_name on iMessage calls causes error (-1728). Omit it.
  - Bare timestamps without timezone offset fail on Reminders.
  - Mail has no "list recent" endpoint. Always pass a search query.
  - Use `search_tools` plus `get_tool_info` to inspect tools without loading every schema into context.
  - Multiple Notes folders exist across accounts. Pick one default.
  - Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
  - Some System actions depend on host app automation approval.
  - Maps search and directions depend on the local Swift helper and Xcode command line tools.
</known_gotchas>
</apple_tools>
```

## Related Servers

- [Apple Files MCP](../AppleFiles-MCP/README.md)
- [Apple System MCP](../AppleSystem-MCP/README.md)
- [Apple Maps MCP](../AppleMaps-MCP/README.md)
- [Apple Mail MCP](../AppleMail-MCP/README.md)
- [Apple Calendar](../Apple-Calendar-MCP/README.md)
- [Apple Reminders MCP](../AppleReminders-MCP/README.md)
- [Apple Messages MCP](../AppleMessages-MCP/README.md)
- [Apple Contacts MCP](../AppleContacts-MCP/README.md)
- [Apple Notes MCP](../AppleNotes-MCP/README.md)
- [Apple Shortcuts MCP](../AppleShortcuts-MCP/README.md)
