🍎 Apple MCP (yfysnp fork)

Apple 原生应用的 MCP 服务器——让 LLM 通过统一接口操作 Contacts、Notes、Messages、Mail、Reminders、Calendar、Maps。

![License: MIT](https://opensource.org/licenses/MIT) ![Platform: macOS](https://www.apple.com/macos/)

This is a maintained fork of the original dhravya/apple-mcp, refactored for clarity and continued maintenance. See Differences from upstream below.

---

✨ Capabilities

| Tool | Operations | |---|---| | contacts | Search/list contacts by name, lookup phone numbers | | notes | Search / list / create notes (with folder support) | | messages | Send, read, schedule iMessages; check unread | | mail | Read unread, search, send (with CC/BCC), list mailboxes/accounts | | reminders | List / search / open / create reminders (per-list scoping) | | calendar | List / search / open / create events (across calendars) | | maps | Search locations, save favorites, get directions, manage guides, drop pins |

Built on AppleScript / JXA under the hood; uses SQLite directly for Messages where appropriate.

---

📦 Installation

Requirement: macOS only. Tools that need Apple app access (Contacts, Calendar, Reminders, Mail, etc.) will require granting Automation permission to your terminal / MCP host on first use. See Permissions below.

Option A — From source (works today)

# 1. Get bun (skip if installed)
brew install oven-sh/bun/bun

# 2. Clone and build
git clone https://github.com/yfysnp/apple-mcp.git
cd apple-mcp
bun install
bun run build      # produces dist/index.js

Then add this entry to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/apple-mcp/dist/index.js"]
    }
  }
}

把 /absolute/path/to/apple-mcp 换成你 clone 出来的实际绝对路径（pwd 看一眼）。

For Cursor or other MCP hosts, point them at the same node dist/index.js command.

Restart your MCP host. The 7 tools should be available.

---

Option B — From GitHub Release (download pre-built bundle)

Releases ship a pre-built dist/index.js so you don't need bun/node toolchain to use it (Node 18+ runtime still required).

Go to Releases and download apple-mcp-<version>.tar.gz.
Extract somewhere stable, e.g.:

   mkdir -p ~/.local/share/apple-mcp
   tar -xzf apple-mcp-1.0.0.tar.gz -C ~/.local/share/apple-mcp --strip-components=1

Add to Claude Desktop config:

   {
     "mcpServers": {
       "apple-mcp": {
         "command": "node",
         "args": ["/Users/you/.local/share/apple-mcp/dist/index.js"]
       }
     }
   }

---

🔐 Permissions

On first use of each tool, macOS will prompt for permission to control the corresponding app. If you accidentally deny, re-grant via:

System Settings → Privacy & Security → Automation → [your MCP host app] → enable [Contacts / Calendar / Mail / ...]

The MCP host (Claude Desktop, Cursor, etc.) is what asks macOS — not this binary. So make sure you're granting permission to the host process, not to node.

For Messages specifically, you also need Full Disk Access for the MCP host (Messages reads the SQLite db at ~/Library/Messages/chat.db).

---

🧪 Local development

bun install
bun run dev        # runs index.ts directly via bun
bun run build      # produces minified dist/index.js
bun run test       # runs integration tests (requires Apple apps available)

Architecture:

index.ts — entry point, eager/lazy module loading, dispatch map
handlers/<tool>.ts — one file per MCP tool (contacts, notes, messages, mail, reminders, calendar, maps)
handlers/_shared.ts — ToolResponse / LoadModule types + response helpers
utils/<tool>.ts — actual AppleScript / JXA implementations
tools.ts — MCP tool schemas

See docs/superpowers/plans/ for design history.

---

🎯 Example prompts

Send a message to mom saying I'll be late for dinner

Find all my AI research notes and email them to sarah@example.com

Create a reminder to call the dentist tomorrow at 2pm

Show my calendar for next week and create an event for coffee with Alex on Friday

Find the nearest pizza place and save it to my favorites

---

📝 Differences from upstream

This fork at yfysnp/apple-mcp makes the following changes vs. dhravya/apple-mcp:

Refactored index.ts from 1720 lines into a 277-line entry + 7 per-tool handler files under handlers/.
Added shared response helpers (textResponse, accessAwareError) and shared types (ToolResponse, LoadModule).
Removed dead utils/web-search.ts and its orphan test runner entries (was never wired into tools.ts or manifest.json).
Standardized error message prefixes across all 7 tools (Error with X operation: ...).
Fixed a latent Promise<string | undefined> type error in mail's send handler.

The upstream repo appears unmaintained. We track upstream as the upstream remote and may pull selective improvements.

---

📤 Cutting a release (maintainer notes)

Bump version in package.json + manifest.json, then tag and push:

git tag v1.0.1
git push origin v1.0.1

The workflow (.github/workflows/release.yml) will build dist/index.js, smoke-test it, and create a GitHub Release with apple-mcp-<version>.tar.gz attached.

---

📄 License

MIT — see LICENSE.

apple-mcp