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
- 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 nameget_all_contacts() -> List[Contact]: Get all contactscreate_contact(name: str, phones: List[str]) -> Contact: Create a new contact
Notes Module
find_note(query: str) -> List[Note]: Search for notescreate_note(title: str, body: str, folder_name: str) -> Note: Create a new noteget_all_notes() -> List[Note]: Get all notes
Mail Module
send_email(to: str, subject: str, body: str) -> str: Send an emailsearch_emails(query: str) -> List[Email]: Search emailsget_unread_mails() -> List[Email]: Get unread emails
Messages Module
send_message(to: str, content: str) -> bool: Send an iMessageread_messages(phone_number: str) -> List[Message]: Read messagesschedule_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 remindersearch_reminders(query: str) -> List[Dict]: Search remindersget_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 eventsearch_events(query: str) -> List[Dict]: Search eventsget_events() -> List[Dict]: Get all events
Maps Module
search_locations(query: str) -> List[Location]: Search for locationsget_directions(from_address: str, to_address: str, transport_type: str) -> str: Get directionssave_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.
Metadata
Release files for iflow-mcp_python-apple-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_python_apple_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_python_apple_mcp-0.1.0-py3-none-any.whl |
Release files / iflow_mcp_python_apple_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_python_apple_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 20.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6af1de8c6198615a216f263af2d1672a9fa2a3cd47424063c7e13a44e284b7ce
|
|
BLAKE2b-256 checksum How to use checksums |
21f681a573857afc942062318da24abc93dd6c1e1624c387c5f72df6bce32323
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_python-apple-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.