MCP AppleReminders

🚀 Apple Reminder MCP Tool Usage Guide

This tool is developed based on the MCP function of Xiaozhi AI (for the development example document, see: mcp-calculator). It allows you to create and query Apple reminders through the MCP protocol. You can set the reminder content (title and note) as well as the reminder date and time.

✨ Features

Create Reminders

• Set a reminder title (required).
• Add a reminder note (optional).
• Set a reminder date (optional, format: YYYY-MM-DD).
• Set a reminder time (optional, format: HH:MM:SS, only valid when a date is provided).

Query Reminders

• Query reminders by date range (e.g., "today", "tomorrow", "this week", etc.).
• Get the full information of reminders (title, note, 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:

pip install -r requirements.txt

2. Set the environment variables:

export MCP_ENDPOINT=<your_mcp_endpoint>

💻 Usage Examples

1. Start the MCP Server

Use mcp_pipe.py to start the reminder server:

python mcp_pipe.py reminder.py

2. Use the Reminder Tool via the AI Assistant

Once the server is started and connected to the AI assistant, you can use the reminder tool with natural language:

Create Reminders

• "Help me create a reminder with the title 'Buy milk' and the note 'Supermarket special offer', and set the date for tomorrow."
• "Set a reminder with the title 'Doctor's appointment' on May 20, 2025, at 3 PM."
• "Add a reminder: Meeting at 2:30 PM on Friday."

Query Reminders

• "Query my reminders for today."
• "What reminders do I have tomorrow?"
• "List all reminders for this week."
• "Check the reminders for May 20."
• "What reminders do I have on Friday?"

🧪 Testing Tools

Test Reminder Creation

You can use the provided test script to test the reminder creation function:

python test_reminder.py

Test Reminder Query

You can use the provided test script to test the reminder query function:

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 reminders for today.
2. Query reminders for tomorrow.
3. Query reminders for this week.

🛠️ Troubleshooting

Common Issues

1. Permission issues: Make sure your app has permission to access reminders. A permission request dialog may pop up on the first run.
2. Incorrect date format: Ensure the date format is YYYY-MM-DD (e.g., 2025-05-18).
3. Incorrect time format: Ensure the time format is HH:MM:SS (e.g., 14:30:00).

Debugging

If you encounter issues, you can check the log output for more information. The logs will be displayed in the terminal.

🧪 Function Testing

When testing this function on a real device, please note the following points:

1. Basic Function Testing

   • Create different types of reminders (without a date, with a date, with a date and time).
   • Verify that the reminders are correctly displayed in the Apple Reminders app.

2. Boundary Case 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 where a required parameter (title) is missing.
   • Test the case where a time is provided without a date.

🚀 Future Improvements

Possible future improvement directions:

1. Support recurring reminders (daily, weekly, monthly, etc.).
2. Support setting reminder priorities.
3. Support adding to specific reminder lists.
4. Support setting location-based reminders.
5. Support querying and modifying existing reminders.