API Reference

Complete documentation for all PyApple MCP tool functions

contacts

Search, add, and manage contacts in Apple Contacts app.

Signature

contacts(operation: str = "search", name: str = None, first_name: str = None, last_name: str = None, phone: str = None, email: str = None) → str

Parameters

operation str "search" Operation to perform: 'search', 'add', or 'delete'
name str None Name to search for (if not provided, returns all contacts)
first_name str None First name for new contact (required for add operation)
last_name str None Last name for new contact (optional for add operation)
phone str None Phone number for new contact (optional for add operation)
email str None Email address for new contact (optional for add operation)

Examples

Search for a contact:
"Search for John Doe in my contacts"

Add a new contact:
"Add a new contact named Alice Smith with email alice@example.com and phone 555-0123"

notes

Search, retrieve, create, and delete notes in Apple Notes app.

Signature

notes(operation: str, search_text: str = None, title: str = None, body: str = None, folder_name: str = "Claude") → str

Parameters

operation str Required Operation to perform: 'search', 'list', 'view', 'create', or 'delete'
search_text str None Text to search for in notes (required for search, view, and delete operations)
title str None Title of the note to create (required for create operation)
body str None Content of the note to create (required for create operation)
folder_name str "Claude" Name of the folder to create the note in (optional for create)

Examples

Create a note:
"Create a note titled 'Meeting Notes' with content 'Discussed project timeline'"

Search notes:
"Find all notes containing 'AI research'"

messages

Interact with Apple Messages app - send, read, schedule messages and check unread messages.

Signature

messages(operation: str, phone_number: str = None, message: str = None, limit: int = 10, scheduled_time: str = None) → str

Parameters

operation str Required Operation to perform: 'send', 'read', 'schedule', or 'unread'
phone_number str None Phone number for send, read, and schedule operations
message str None Message to send (required for send and schedule operations)
limit int 10 Number of messages to read (optional, for read and unread operations)
scheduled_time str None ISO string of when to send message (required for schedule operation)

Examples

Send a message:
"Send a message to +1234567890 saying 'Hello from Claude!'"

Read recent messages:
"Show me the last 5 messages from +1234567890"

mail

Interact with Apple Mail app - read unread emails, search emails, and send emails. Features optimized local database search for performance.

Signature

mail(operation: str, account: str = None, mailbox: str = None, limit: int = 10, search_term: str = None, to: str = None, subject: str = None, body: str = None, cc: str = None, bcc: str = None, full_content: bool = False, search_range: int = None, mark_read: bool = False) → str

Parameters

operation str Required Operation to perform: 'unread', 'search', 'send', 'mailboxes', or 'accounts'
account str None Email account to use (searches all accounts if not specified)
search_term str None Text to search for in emails (required for search operation)
to str None Recipient email address (required for send operation)
subject str None Email subject (required for send operation)
body str None Email body content (required for send operation)
full_content bool False If True, return full email content without truncation

Examples

Search emails:
"Search for emails containing 'project update' in the last 50 messages"

Send an email:
"Send an email to john@example.com with subject 'Meeting Follow-up' and body 'Thanks for the productive meeting'"

reminders

Search, create, and open reminders in Apple Reminders app.

Signature

reminders(operation: str, search_text: str = None, name: str = None, list_name: str = None, list_id: str = None, props: List[str] = None, notes: str = None, due_date: str = None, show_completed: bool = False) → str

Parameters

operation str Required Operation to perform: 'list', 'search', 'open', 'create', or 'listById'
name str None Name of the reminder to create (required for create operation)
due_date str None Due date for reminder in ISO format (optional for create operation)
notes str None Additional notes for reminder (optional for create operation)
show_completed bool False Whether to show completed reminders (shows only incomplete by default)

Examples

Create a reminder:
"Create a reminder to 'Buy groceries' for tomorrow at 5pm"

List reminders:
"Show me all my incomplete reminders"

calendar

Search, create, delete, move, and open calendar events in Apple Calendar app.

Signature

calendar(operation: str, search_text: str = None, title: str = None, start_date: str = None, end_date: str = None, location: str = None, notes: str = None, is_all_day: bool = False, calendar_name: str = None, invitees: List[str] = None) → str

Parameters

operation str Required Operation to perform: 'search', 'open', 'list', 'create', 'delete', 'move', or 'calendars'
title str None Title of the event to create (required for create operation)
start_date str None Start date/time of the event in ISO format (required for create)
end_date str None End date/time of the event in ISO format (required for create)
location str None Location of the event (optional for create operation)
invitees List[str] None List of email addresses to invite to the event (optional for create operation)
is_all_day bool False Whether the event is an all-day event

Examples

Create an event:
"Create a calendar event 'Team Meeting' from 2024-01-15T14:00:00 to 2024-01-15T15:00:00 at Conference Room A"

Search events:
"Find all calendar events this week containing 'meeting'"

maps

Search locations, manage guides, save favorites, and get directions using Apple Maps.

Signature

maps(operation: str, query: str = None, from_address: str = None, to_address: str = None, transport_type: str = "driving") → str

Parameters

operation str Required Operation to perform (search, directions, etc.)
query str None Search query for locations (required for search)
from_address str None Starting address for directions (required for directions)
to_address str None Destination address for directions (required for directions)
transport_type str "driving" Type of transport to use (optional for directions)

Examples

Search locations:
"Search for coffee shops near Apple Park"

Get directions:
"Get driving directions from Apple Park to San Francisco Airport"