Enables interaction with Apple's ecosystem through AppleScript, allowing access to native macOS applications and their data.

Project is hosted on GitHub and supports contribution through GitHub's pull request workflow.

Allows sending, reading, and scheduling iMessages through the Messages application, including accessing conversation history.

Provides tools for interacting with native macOS applications such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps.

Uses Pydantic models to provide type-safe interfaces for working with data from macOS applications.

Supports comprehensive testing of the MCP functionality with pytest, including coverage reporting.

Implemented in Python, providing a programmatic interface to macOS applications through a Python API.

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

Related MCP server: macOS Automator MCP Server

Supported Applications

Contacts
Notes
Mail
Messages
Reminders
Calendar
Maps

Installation

Clone the repository:

git clone https://github.com/jxnl/python-apple-mcp.git cd python-apple-mcp

Create a virtual environment:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Install test dependencies (optional):

pip install -r requirements-test.txt

Usage

Basic Example

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

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:

pytest

Run tests with coverage:

pytest --cov=utils tests/

Run specific test file:

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

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Python Apple MCP