# Python Apple MCP (Model Context Protocol) A Python implementation of the server that handles interactions with macOS applications such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps using FastMCP. ## 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: \`\`\`bash git clone https://github.com/jxnl/python-apple-mcp.git cd python-apple-mcp \`\`\` 2. Create a virtual environment: \`\`\`bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate \`\`\` 3. Install dependencies: \`\`\`bash pip install -r requirements.txt \`\`\` 4. Install test dependencies (optional): \`\`\`bash pip install -r requirements-test.txt \`\`\` ## Usage ### Basic Example \`\`\`python from apple_mcp import FastMCP, Context # Initialize FastMCP server mcp = FastMCP("Apple MCP") # Use the tools @mcp.tool() def find_contact(name: str) -> List[Contact]: """Search for contacts by name""" # Implementation here pass # Run the server if __name__ == "__main__": mcp.run() \`\`\` ### Using Individual Modules \`\`\`python from utils.contacts import ContactsModule from utils.notes import NotesModule # Initialize modules contacts = ContactsModule() notes = NotesModule() # Use the modules async def main(): # Find a contact contact = await contacts.find_contact("John") # Create a note await notes.create_note( title="Meeting Notes", body="Discussion points...", folder_name="Work" ) # Run the async code import asyncio asyncio.run(main()) \`\`\` ## Testing Run the test suite: \`\`\`bash pytest \`\`\` Run tests with coverage: \`\`\`bash pytest --cov=utils tests/ \`\`\` Run specific test file: \`\`\`bash pytest tests/test_contacts.py \`\`\` ## 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 This project is licensed under the MIT License - see the LICENSE file for details.