# apple-mcp

> Apple Apps MCP Server — control Messages, Notes, Reminders, Calendar, Contacts, and Photos through AppleScript.

[![PyPI version](https://img.shields.io/pypi/v/apple-mcp.svg)](https://pypi.org/project/apple-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)

> **macOS only** — requires macOS with Automation permissions granted to your terminal / Claude Code.

**27 tools** across 6 Apple apps — fully offline, no API keys, no network calls. All data stays on your Mac.

## Tools

### Messages (5)
| Tool | Description |
|------|-------------|
| `messages_list_chats` | List all conversations |
| `messages_get_chat` | Get messages from a specific conversation |
| `messages_get_recent` | Get recent messages across all chats |
| `messages_search` | Search messages by content |
| `messages_send` | Send an iMessage or SMS |

### Notes (5)
| Tool | Description |
|------|-------------|
| `notes_list_folders` | List all Notes folders |
| `notes_list` | List notes (optionally filter by folder) |
| `notes_get` | Get the full content of a note |
| `notes_create` | Create a new note |
| `notes_search` | Search notes by content |

### Reminders (5)
| Tool | Description |
|------|-------------|
| `reminders_list_lists` | List all Reminder lists |
| `reminders_list` | List reminders (optionally filter by list) |
| `reminders_create` | Create a reminder with optional due date |
| `reminders_complete` | Mark a reminder as complete |
| `reminders_search` | Search reminders by name |

### Calendar (4)
| Tool | Description |
|------|-------------|
| `calendar_list` | List all calendars |
| `calendar_today` | Get today's events |
| `calendar_events` | Get events in a date range |
| `calendar_create_event` | Create a new calendar event |

### Contacts (4)
| Tool | Description |
|------|-------------|
| `contacts_list` | List all contacts |
| `contacts_search` | Search by name, email, or phone |
| `contacts_get` | Get detailed contact information |
| `contacts_groups` | List contact groups |

### Photos (4)
| Tool | Description |
|------|-------------|
| `photos_list_albums` | List all photo albums |
| `photos_recent` | Get recently added photos |
| `photos_album` | Get photos from a specific album |
| `photos_search` | Search photos by keyword |

---

## Setup

### Requirements

- **macOS** (AppleScript is macOS-only)
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager

### Step 1 — Install

```bash
pip install apple-mcp
# or with uv:
uv add apple-mcp
```

### Step 2 — Grant Permissions

The first time each app is accessed, macOS will prompt for Automation permission. You can also grant them upfront:

1. Open **System Settings** → **Privacy & Security** → **Automation**
2. Find your terminal app (Terminal, iTerm2) or Claude Code
3. Enable access for: **Messages**, **Notes**, **Reminders**, **Calendar**, **Contacts**, **Photos**

> For Messages, full disk access may be needed for reading message history. Go to **Privacy & Security** → **Full Disk Access** and add your terminal app.

### Step 3 — Add to Claude Code

```bash
claude mcp add apple -- uvx apple-mcp
```

Or manually in your Claude config (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "apple": {
      "command": "uvx",
      "args": ["apple-mcp"]
    }
  }
}
```

---

## Privacy & Security

- **Fully offline** — no network requests, no third-party APIs
- All data stays on your Mac
- Uses AppleScript and local SQLite database (`~/Library/Messages/chat.db`) for Messages
- No credentials or tokens required

---

## Troubleshooting

**"Not authorized to send Apple events":**
Go to System Settings → Privacy & Security → Automation and enable the app.

**Messages not showing:**
Ensure Full Disk Access is granted to your terminal app (System Settings → Privacy & Security → Full Disk Access).

**Photos tools slow:**
Photos.app must be running. Large libraries may take a moment to query.

**Calendar/Reminders not responding:**
Open the respective app once manually to ensure it initializes properly.

---

## Requirements

- macOS (10.15 Catalina or later recommended)
- Python 3.10+
- Automation permissions in System Settings

## License

MIT — [Hitesh Gupta](https://github.com/dev-hitesh-gupta)
