What is Python Apple Mcp

python-apple-mcp is a Python implementation of the Model Context Protocol (MCP) that facilitates interactions with macOS applications such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps using FastMCP.

Use cases

Use cases include searching for contacts, creating notes, managing reminders, sending messages, and handling calendar events programmatically within macOS applications.

How to use

To use python-apple-mcp, clone the repository, create a virtual environment, install dependencies, and run the server. You can define tools to interact with macOS applications and execute asynchronous operations for better performance.

Key features

Key features include interaction with macOS native applications through AppleScript, asynchronous operations, comprehensive error handling, type-safe interfaces using Pydantic models, extensive test coverage, and a modular design for easy extension.

Where to use

python-apple-mcp can be used in software development environments where integration with macOS applications is required, particularly in automation, data management, and application development.

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:

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

2. Create a virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. 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

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.