https://github.com/jxnl/python-apple-mcp
https://github.com/jxnl/python-apple-mcp
Last synced: 10 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/jxnl/python-apple-mcp
- Owner: jxnl
- Created: 2025-04-02T20:58:46.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-04-29T18:04:57.000Z (8 months ago)
- Last Synced: 2025-04-29T19:22:33.012Z (8 months ago)
- Language: Python
- Size: 30.3 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- metorial-index - Python Apple MCP - Interact with macOS applications using AppleScript to automate tasks across various native apps such as Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps. Provides asynchronous operations and type-safe interfaces for efficient application interactions. (Scheduling and Calendars)
- toolsdk-mcp-registry - ❌ apple-macos-native-applications
README
# 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:
```bash
git clone https://github.com/jxnl/python-apple-mcp.git
cd python-apple-mcp
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Install test dependencies (optional):
```bash
pip install -r requirements-test.txt
```
## Usage
### Basic Example
```python
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
```python
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:
```bash
pytest
```
Run tests with coverage:
```bash
pytest --cov=utils tests/
```
Run specific test file:
```bash
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.