Python-based Model Context Protocol server enabling asynchronous, type-safe interactions with macOS native apps like Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps through AppleScript integration and modular design.
Unlock the full potential of Python Apple MCP through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.
Free tier available • No credit card required
A Python implementation of the server that handles interactions with macOS applications such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps using FastMCP.
git clone https://github.com/jxnl/python-apple-mcp.git cd python-apple-mcp
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-test.txt
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()
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())
Run the test suite:
pytest
Run tests with coverage:
pytest --cov=utils tests/
Run specific test file:
pytest tests/test_contacts.py
find_contact(name: str) -> List[Contact]
: Search for contacts by nameget_all_contacts() -> List[Contact]
: Get all contactscreate_contact(name: str, phones: List[str]) -> Contact
: Create a new contactfind_note(query: str) -> List[Note]
: Search for notescreate_note(title: str, body: str, folder_name: str) -> Note
: Create a new noteget_all_notes() -> List[Note]
: Get all notessend_email(to: str, subject: str, body: str) -> str
: Send an emailsearch_emails(query: str) -> List[Email]
: Search emailsget_unread_mails() -> List[Email]
: Get unread emailssend_message(to: str, content: str) -> bool
: Send an iMessageread_messages(phone_number: str) -> List[Message]
: Read messagesschedule_message(to: str, content: str, scheduled_time: str) -> Dict
: Schedule a messagecreate_reminder(name: str, list_name: str, notes: str, due_date: str) -> Dict
: Create a remindersearch_reminders(query: str) -> List[Dict]
: Search remindersget_all_reminders() -> List[Dict]
: Get all reminderscreate_event(title: str, start_date: str, end_date: str, location: str, notes: str) -> Dict
: Create an eventsearch_events(query: str) -> List[Dict]
: Search eventsget_events() -> List[Dict]
: Get all eventssearch_locations(query: str) -> List[Location]
: Search for locationsget_directions(from_address: str, to_address: str, transport_type: str) -> str
: Get directionssave_location(name: str, address: str) -> Dict
: Save a location to favoritesThis project is licensed under the MIT License - see the LICENSE file for details.
Discover shared experiences
Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!