MCP-AppleReminders

# Apple Reminders MCP Tool Usage Guide This tool is developed based on the MCP function of Xiaozhi AI (see the development example document: [mcp-calculator](https://github.com/78/mcp-calculator)), allowing the creation and querying of Apple Reminders via the MCP protocol. It can set reminder content (title and notes) as well as reminder date and time. ## Features ### Create Reminder - Set reminder title (required) - Add reminder notes (optional) - Set reminder date (optional, format: YYYY-MM-DD) - Set reminder time (optional, format: HH:MM:SS, requires a date to be effective) ### Query Reminder - Query reminders by date range (e.g., "today", "tomorrow", "this week", etc.) - Get complete information about reminders (title, notes, date and time) - Support natural language date expressions (e.g., "today", "tomorrow", "Friday", etc.) ## Installation and Configuration 1. Make sure you have installed the required dependencies: ```bash pip install -r requirements.txt ``` 2. Set environment variables: ```bash export MCP_ENDPOINT=<your_mcp_endpoint> ``` ## How to Use ### 1. Start the MCP Server Use `mcp_pipe.py` to start the reminder server: ```bash python mcp_pipe.py reminder.py ``` ### 2. Use the Reminder Tool via AI Assistant Once the server is started and connected to the AI assistant, you can use the reminder tool with natural language: #### Create Reminder - "Create a reminder for me, the title is 'Buy milk', the note is 'Supermarket special', the date is tomorrow" - "Set a reminder, the title is 'Doctor appointment', the date is May 20, 2025, the time is 3 pm" - "Add a reminder: Meeting at 2:30 pm on Friday" #### Query Reminder - "Query my reminders for today" - "What reminders do I have tomorrow?" - "List all reminders for this week" - "View reminders for May 20" - "What reminders do I have on Friday?" ## Test Tool ### Test Create Reminder You can use the provided test script to test the reminder creation function: ```bash python test_reminder.py ``` ### Test Query Reminder You can use the provided test script to test the reminder query function: ```bash python test_get_reminders.py ``` The test script for creating reminders will run several test cases, including: 1. Create a reminder without a date 2. Create a reminder with only a date 3. Create a reminder with a date and time The test script for querying reminders will run the following test cases: 1. Query today's reminders 2. Query tomorrow's reminders 3. Query this week's reminders ## Troubleshooting ### Common Issues 1. **Permission Issues**: Make sure your app has permission to access reminders. A permission request dialog may pop up the first time you run it. 2. **Incorrect Date Format**: Make sure the date format is YYYY-MM-DD (e.g. 2025-05-18). 3. **Incorrect Time Format**: Make sure the time format is HH:MM:SS (e.g. 14:30:00). ### Debugging If you encounter problems, you can view the log output for more information. The logs will be displayed in the terminal. ## Functional Testing When testing this feature on a real device, please note the following: 1. **Basic Functionality Testing**: - Create different types of reminders (no date, with date, with date and time) - Verify that reminders are displayed correctly in the Apple Reminders app 2. **Boundary Condition Testing**: - Test the handling of special characters in titles and notes - Test past dates and times - Test invalid date and time formats 3. **Error Handling Testing**: - Test the case of missing required parameters (title) - Test the case of providing time but not date ## Further Improvements Possible future improvements: 1. Support recurring reminders (daily, weekly, monthly, etc.) 2. Support setting reminder priority 3. Support adding to a specific reminder list 4. Support setting location reminders 5. Support querying and modifying existing reminders