# 🍎 Apple MCP (yfysnp fork)

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform: macOS](https://img.shields.io/badge/Platform-macOS-blue.svg)](https://www.apple.com/macos/)

This is a maintained fork of the original [`dhravya/apple-mcp`](https://github.com/dhravya/apple-mcp), refactored for clarity and continued maintenance. See [Differences from upstream](#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](#permissions) below.

### Option A — From source (works today)

```bash
# 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`):

```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).

1. Go to [Releases](https://github.com/yfysnp/apple-mcp/releases) and download `apple-mcp-<version>.tar.gz`.
2. Extract somewhere stable, e.g.:
   ```bash
   mkdir -p ~/.local/share/apple-mcp
   tar -xzf apple-mcp-1.0.0.tar.gz -C ~/.local/share/apple-mcp --strip-components=1
   ```
3. Add to Claude Desktop config:
   ```json
   {
     "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

```bash
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/`](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`](https://github.com/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:

```bash
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](LICENSE).

Original work © Dhravya Shah / Supermemory team. Fork maintained by [@yfysnp](https://github.com/yfysnp).