Apple Reminders MCP Server v0.2.0

A comprehensive Model Context Protocol (MCP) server for Apple Reminders on macOS, enabling AI assistants like Claude and Cursor AI to manage reminders using natural language.

🎉 What's New in v0.2.0

• ✅ Full CRUD operations (create, read, update, delete)

• ✅ Recurring reminders (daily, weekly, monthly, yearly patterns)

• ✅ Location-based reminders (geofence triggers for arriving/leaving)

• ✅ Multiple alarms per reminder (absolute & relative)

• ✅ Search functionality (text search in title and notes)

• ✅ Date-based queries (today, overdue, completed)

• ✅ 12 MCP tools (up from 3 in v0.1.0)

Features

✨ Comprehensive Integration

• Full CRUD on reminders (create, read, update, delete, complete)

• Search and filter reminders

• Date-based queries (today, overdue, completed)

• ~70% feature coverage of Apple Reminders

🚀 Powered by EventKit + Swift

• Native EventKit integration for best performance

• ✅ Recurring reminders (daily, weekly, monthly, custom)

• ✅ Location-based reminders (arrive/depart triggers)

• ✅ Multiple alarms per reminder

• ✅ Tag workarounds (encoded in notes)

🔒 Privacy First

• All operations happen locally on your Mac

• No cloud services or external APIs

• Respects macOS permission system

Prerequisites

• macOS 13.0+ (Ventura or later)

• Node.js 18+

• Swift 5.9+ (Xcode Command Line Tools)

Quick Start

1. Install & Build

2. Request Permissions

Grant permission in System Settings > Privacy & Security > Reminders.

3. Configure Your AI Assistant

For Claude Desktop

Edit ~/.config/claude/claude_desktop_config.json:

For Cursor AI

Edit your Cursor MCP settings to add this server with the same configuration.

4. Restart Your AI Assistant

Restart Claude Desktop or Cursor to load the MCP server.

Available Tools (12 Total)

Reminder Management (6 tools)

1. create_reminder - Create reminders with comprehensive attributes

   • Basic: title, notes, due date, priority, tags, URL

   • Advanced: recurring patterns, location triggers, multiple alarms

2. update_reminder - Update existing reminders

3. delete_reminder - Permanently delete reminders

4. complete_reminder - Mark reminder as complete

5. uncomplete_reminder - Mark reminder as incomplete

6. get_reminders - List all reminders (filter by completion)

List Management (1 tool)

7. get_all_lists - Get all reminder lists

Search & Query (5 tools)

8. search_reminders - Search by text in title/notes

9. get_todays_reminders - Get reminders due today

10. get_overdue_reminders - Get past-due reminders

11. get_completed_reminders - Get completed reminders (optional date range)

Usage Examples

Basic Reminders

Recurring Reminders

Location-Based Reminders

Search & Filters

Advanced Features

Architecture

Why EventKit + Swift?

This project uses Apple's EventKit framework via a Swift CLI, rather than the simpler JXA (JavaScript for Automation) approach. Here's why:

JXA Limitations (POC tested and documented):

• ❌ No support for recurring reminders (daily, weekly, monthly patterns)

• ❌ No support for location-based reminders (geofencing)

• ❌ No access to tags (would require text workarounds)

• ❌ No support for subtasks (not exposed in API)

• ❌ Multiple alarms not accessible

• ❌ JXA is essentially abandoned by Apple (no updates since 2014)

EventKit Advantages:

• ✅ Full access to 70%+ of Reminders features via official Apple API

• ✅ Native support for recurring reminders with complex rules

• ✅ Native support for location triggers (arrive/depart)

• ✅ Native support for multiple alarms per reminder

• ✅ Actively maintained by Apple with new macOS releases

• ✅ Better performance and reliability

Trade-off: EventKit requires Swift compilation, but the benefits far outweigh the minimal additional setup complexity. The Swift CLI is built once during installation and provides access to nearly all Reminders features that are publicly available.

Feature Coverage (~70%)

✅ Fully Supported

• Core Operations: Create, read, update, delete, complete

• Recurring Reminders: Daily, weekly, monthly, yearly with custom rules

• Location Reminders: Geofence triggers (arriving/leaving)

• Multiple Alarms: Absolute (specific time) and relative (before due date)

• Search: Text search in title and notes

• Date Queries: Today, overdue, completed with date ranges

• Lists: Get all lists, specify list for reminders

• Priority: 0=none, 1=urgent (!!!), 5=medium, 9=low

• Flagged Status: Mark reminders as important (flag icon)

• Notes & URLs: Rich text notes, associated URLs

⚠️ Workarounds

• Tags: Encoded as [#tag] in notes field (searchable)

• Subtasks: Use structured notes or linked reminders

⚠️ API Limitations (Not Yet Available in EventKit)

• Urgent Alarms (macOS 26.2+): The new "Urgent" alarm feature is NOT exposed in EventKit API

  • Workaround: Use priority: 1 + flagged: true + regular alarms

  • See URGENT_FEATURE_STATUS.md for details

• Apple has not announced when/if EventKit will support this feature

❌ Not Supported (Private Apple APIs)

• Native tags feature

• Subtasks feature

• Smart lists

Development

Project Structure

Development Commands

Building from Source

Testing

Test Swift CLI Directly

Test with MCP Inspector

Advanced Features

Recurring Reminders

Create reminders that repeat on a schedule:

Location-Based Reminders

Trigger reminders based on location:

Multiple Alarms

Add multiple notifications to a reminder:

Troubleshooting

Permission Denied

1. Run ./swift-cli/.build/release/reminders-cli request-access

2. Grant permission in System Settings > Privacy & Security > Reminders

3. Restart your AI assistant

Swift CLI Not Found

1. Build the Swift CLI: npm run build:swift

2. Verify: ls swift-cli/.build/release/reminders-cli

Tool Not Working

1. Check Swift CLI directly with test JSON

2. Check MCP server logs in your AI assistant

3. Use MCP Inspector for isolated debugging

Roadmap

✅ Completed

• Full CRUD operations

• Search and filters

• Date-based queries

• Recurring reminders

• Location-based reminders

• Multiple alarms

🔄 Future Enhancements

• List management (create, update, delete lists)

• Batch operations

• Rich error messages with suggestions

• Performance optimization

• Pre-compiled binaries for distribution

• npm package publication

Contributing

This is a learning project. Contributions, issues, and feature requests are welcome!

License

MIT

References

• MCP Documentation

• EventKit Documentation

• FradSer's mcp-server-apple-events

Built with ❤️ for the MCP ecosystem

Version 0.2.0 | Updated January 2026