PyApple MCP Tools

A Python implementation of Apple-native tools for the Model Context Protocol (MCP), providing seamless integration with macOS applications.

Features

• Messages: Send and read messages using the Apple Messages app

• Notes: List, search, create, and delete notes in Apple Notes app

• Contacts: Search contacts from Apple Contacts

• Emails: Send emails, search messages, and manage mail with Apple Mail

• Reminders: List, search, and create reminders in Apple Reminders app

• Calendar: Search events, create calendar entries, and manage your schedule

• Web Search: Search the web using DuckDuckGo

• Maps: Search locations, get directions, and manage guides with Apple Maps

Quick Installation

Automated Setup (Recommended)

The setup helper will:

• Find your pyapple-mcp installation

• Locate your Claude Desktop config file

• Automatically add the configuration

• Display helpful setup information

Manual Installation

1. Install pyapple-mcp:

   pip install pyapple-mcp

2. Configure Claude Desktop by editing ~/Library/Application Support/Claude Desktop/claude_desktop_config.json:

   { "mcpServers": { "pyapple": { "command": "pyapple-mcp" } } }

3. Restart Claude Desktop to load the new configuration.

Usage Examples

Basic Commands

Advanced Workflows

You can chain commands together for complex workflows:

Development

Local Setup

1. Clone the repository:

   git clone https://github.com/pyapple-mcp/pyapple-mcp.git cd pyapple-mcp

2. Install dependencies:

   pip install -e ".[dev]"

3. Run the development server:

   python -m pyapple_mcp.server

Testing with MCP Inspector

Requirements

• macOS 10.15+ (Catalina or later)

• Python 3.10+

• Appropriate permissions for accessing:

  • Contacts

  • Calendar

  • Messages

  • Mail

  • Notes

  • Reminders

  • Automation (for controlling apps)

Permissions Setup

On first use, macOS will prompt for various permissions. Grant access to:

1. Contacts - for contact search functionality

2. Calendar - for calendar event management

3. Messages - for sending/reading messages

4. Mail - for email operations

5. Notes - for notes access

6. Reminders - for reminder management

7. Automation - for controlling applications via AppleScript

Troubleshooting

Common Issues

Permission Denied Errors:

• Go to System Settings > Privacy & Security

• Grant access to the required applications

• Restart Claude Desktop

Module Import Errors:

• Ensure you're running on macOS

• Install PyObjC frameworks: pip install pyobjc

AppleScript Execution Errors:

• Check that the target applications are installed

• Verify automation permissions in System Settings

Setup Issues:

• Run pyapple-mcp-setup --help for setup options

• Check that pyapple-mcp is in your PATH: which pyapple-mcp

• Use pyapple-mcp-setup --config-path /path/to/config for custom config locations

Debug Mode

Run with debug logging:

Architecture

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Make your changes

4. Run tests: pytest

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by the original apple-mcp TypeScript implementation

• Built with the MCP Python SDK

• Uses PyObjC for macOS system integration