Apple Macos Native Applications

🚀 Python Apple MCP (Model Context Protocol)

A Python server implementation using FastMCP to handle macOS applications such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps.

✨ Features

• Interact with macOS native applications using Apple Script.
• Asynchronous operations for improved performance.
• Comprehensive error handling.
• Type-safe interfaces using Pydantic models.
• Extensive test coverage.
• Modular design for easy expansion.

📦 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 Examples

Basic Usage

from apple_mcp import FastMCP, Context
from typing import List
from utils.contacts import Contact

# Initialize the FastMCP server
mcp = FastMCP("Apple MCP")

# Use a tool
@mcp.tool()
def find_contact(name: str) -> List[Contact]:
    """Search for contacts by name"""
    # Implementation code goes here
    pass

# Run the server
if __name__ == "__main__":
    mcp.run()

Using Modules Independently

from utils.contacts import ContactsModule
from utils.notes import NotesModule
import asyncio

# Initialize modules
contacts = ContactsModule()
notes = NotesModule()

# Use modules
async def main():
    # Find a contact
    contact = await contacts.find_contact("John")
    
    # Create a note
    await notes.create_note(
        title="Meeting Minutes",
        body="Discussion points...",
        folder_name="Work"
    )

# Run asynchronous code
asyncio.run(main())

🧪 Testing

Run the test suite:

pytest

Run tests with coverage:

pytest --cov=utils tests/

Run a specific test file:

pytest tests/test_contacts.py

📚 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 for emails.
• get_all_emails() -> List[Email]: Get all emails.

Messages Module

• send_message(to: str, text: str) -> Message: Send a message.
• search_messages(query: str) -> List[Message]: Search for messages.
• get_all_messages() -> List[Message]: Get all messages.

Reminders Module

• create_reminder(title: str, due_date: datetime) -> Reminder: Create a reminder.
• search_reminders(query: str) -> List[Reminder]: Search for reminders.
• get_all_reminders() -> List[Reminder]: Get all reminders.

Calendar Module

• create_event(title: str, start_date: datetime, end_date: datetime) -> Event: Create an event.
• search_events(query: str) -> List[Event]: Search for events.
• get_all_events() -> List[Event]: Get all events.

Maps Module

• get_directions(start: Location, end: Location) -> Directions: Get directions.
• search_places(name: str) -> List[Place]: Search for places.
• get_map_image(bounds: Bounds) -> bytes: Get a map image.

🤝 Contributing

Contributions are welcome! Please refer to the CONTRIBUTING.md file in the project repository.

📄 License

This project is licensed under the MIT License.