Python Apple MCP

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

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.