Skip to main content
Glama

Python Apple MCP

by jxnl

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
  1. Create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. 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.

-
security - not tested
F
license - not found
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A Python server that enables interaction with macOS native applications (Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps) through AppleScript, featuring asynchronous operations and type-safe interfaces.

  1. Features
    1. Supported Applications
      1. Installation
        1. Usage
          1. Basic Example
          2. Using Individual Modules
        2. Testing
          1. API Documentation
            1. Contacts Module
            2. Notes Module
            3. Mail Module
            4. Messages Module
            5. Reminders Module
            6. Calendar Module
            7. Maps Module
          2. Contributing
            1. License

              Related MCP Servers

              • -
                security
                A
                license
                -
                quality
                A macOS app that provides an MCP server to your Messages, Contacts, and more
                Last updated 2 days ago
                719
                MIT License
                • Apple
              • A
                security
                A
                license
                A
                quality
                A Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.
                Last updated 2 months ago
                1
                569
                312
                JavaScript
                MIT License
                • Apple
              • A
                security
                F
                license
                A
                quality
                A collection of tools that enable AI assistants to interact with Apple applications and services including Contacts, Notes, Messages, Mail, Reminders, Calendar, Maps, and Web Search through the Model Context Protocol.
                Last updated 3 months ago
                8
                TypeScript
                • Apple
              • A
                security
                A
                license
                A
                quality
                Provides a Model Context Protocol server for executing AppleScript and JavaScript for Automation scripts on macOS, featuring a knowledge base of pre-defined scripts and supporting automation of macOS applications and system functions.
                Last updated 5 days ago
                2
                566
                397
                TypeScript
                MIT License
                • Apple

              View all related MCP servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/jxnl/python-apple-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server