Python Apple MCP (Model Context Protocol)

Features

• Interact with macOS native applications through AppleScript

• Asynchronous operations for better performance

• Comprehensive error handling

• Type-safe interfaces using Pydantic models

• Extensive test coverage

• Modular design for easy extension

Supported Applications

• Contacts

• Notes

• Mail

• Messages

• Reminders

• Calendar

• Maps

Installation

1. Clone the repository:

1. Create a virtual environment:

1. Install dependencies:

1. Install test dependencies (optional):

Usage

Basic Example

Using Individual Modules

Testing

API Documentation

Contacts Module

• `find_contact(name: str) -> List[Contact]`: Search for contacts by name

• `get_all_contacts() -> List[Contact]`: Get all contacts

• `create_contact(name: str, phones: List[str]) -> Contact`: Create a new contact

Notes Module

• `find_note(query: str) -> List[Note]`: Search for notes

• `create_note(title: str, body: str, folder_name: str) -> Note`: Create a new note

• `get_all_notes() -> List[Note]`: Get all notes

Mail Module

• `send_email(to: str, subject: str, body: str) -> str`: Send an email

• `search_emails(query: str) -> List[Email]`: Search emails

• `get_unread_mails() -> List[Email]`: Get unread emails

Messages Module

• `send_message(to: str, content: str) -> bool`: Send an iMessage

• `read_messages(phone_number: str) -> List[Message]`: Read messages

• `schedule_message(to: str, content: str, scheduled_time: str) -> Dict`: Schedule a message

Reminders Module

• `create_reminder(name: str, list_name: str, notes: str, due_date: str) -> Dict`: Create a reminder

• `search_reminders(query: str) -> List[Dict]`: Search reminders

• `get_all_reminders() -> List[Dict]`: Get all reminders

Calendar Module

• `create_event(title: str, start_date: str, end_date: str, location: str, notes: str) -> Dict`: Create an event

• `search_events(query: str) -> List[Dict]`: Search events

• `get_events() -> List[Dict]`: Get all events

Maps Module

• `search_locations(query: str) -> List[Location]`: Search for locations

• `get_directions(from_address: str, to_address: str, transport_type: str) -> str`: Get directions

• `save_location(name: str, address: str) -> Dict`: Save a location to favorites

Contributing

1. Fork the repository

2. Create a feature branch

3. Commit your changes

4. Push to the branch

5. Create a Pull Request

License