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

# Clone or download this repository
cd apple-reminders-mcp-server

# Run setup (installs dependencies and builds everything)
npm run setup

2. Request Permissions

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

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

3. Configure Your AI Assistant

For Claude Desktop

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

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/apple-reminders-mcp-server/dist/index.js"]
    }
  }
}

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

"Create a reminder to buy milk"
"Show me all my reminders"
"Mark the milk reminder as complete"
"Delete the milk reminder"

Recurring Reminders

"Create a weekly reminder for team meeting every Monday at 10am"
"Set up a daily reminder to take medication at 8am"
"Create a monthly reminder on the 1st to pay rent"

Location-Based Reminders

"Remind me to buy groceries when I arrive at the supermarket"
"Create a reminder to call mom when I leave work"

Search & Filters

"Search for reminders about meetings"
"Show me today's reminders"
"What reminders are overdue?"
"Show me completed reminders from last week"

Advanced Features

""Create an URGENT reminder with priority 1 to call the client"
"Create a high-priority reminder with tags #work #urgent""
"Set up a reminder with multiple alarms - 1 day before and 1 hour before"
"Create a reminder that repeats every other week"

Architecture

AI Assistant (Claude/Cursor)
    ↓ MCP Protocol (stdio)
TypeScript MCP Server (Node.js)
    ↓ child_process + JSON
Swift CLI Binary (EventKit)
    ↓ EventKit Framework
Apple Reminders.app

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

apple-reminders-mcp-server/
├── swift-cli/              # Swift CLI (EventKit integration)
│   ├── Sources/
│   │   ├── RemindersKit/   # Core library
│   │   │   ├── Models/     # Swift models
│   │   │   └── *.swift     # Managers
│   │   └── reminders-cli/  # CLI executable
│   └── Package.swift
├── src/                    # TypeScript MCP Server
│   ├── index.ts           # MCP server entry
│   ├── executor/          # Swift CLI executor
│   ├── tools/             # 12 MCP tool handlers
│   ├── validation/        # Zod schemas
│   └── types/             # TypeScript types
└── docs/                  # Documentation

Development Commands

# Build everything
npm run build          # Build TypeScript
npm run build:swift    # Build Swift CLI

# Development mode
npm run dev            # Watch mode for TypeScript

# Testing
npm test               # Run tests
npm run lint           # Lint code
npm run format         # Format code

# Cleanup
npm run clean          # Remove build artifacts

Building from Source

# Build Swift CLI (release mode)
cd swift-cli
swift build --configuration release

# Build TypeScript
cd ..
npm run build

Testing

Test Swift CLI Directly

# Create an urgent reminder (priority 1 = shows !!! in Reminders.app)
./swift-cli/.build/release/reminders-cli create-reminder '{"title":"URGENT: Fix bug","priority":1}'

# Create recurring reminder
./swift-cli/.build/release/reminders-cli create-reminder '{
  "title":"Weekly Meeting",
  "dueDate":"2026-01-13T10:00:00Z",
  "recurrence":{"frequency":"weekly","interval":1}
}'

# Search reminders
./swift-cli/.build/release/reminders-cli search-reminders '{"searchText":"meeting"}'

# Get today's reminders
./swift-cli/.build/release/reminders-cli get-todays-reminders

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Advanced Features

Recurring Reminders

Create reminders that repeat on a schedule:

{
  "title": "Weekly team sync",
  "dueDate": "2026-01-13T10:00:00Z",
  "recurrence": {
    "frequency": "weekly",    // daily, weekly, monthly, yearly
    "interval": 1,            // every N weeks
    "daysOfWeek": [2],        // Monday (1=Sunday, 7=Saturday)
    "endDate": "2026-12-31T00:00:00Z"  // optional
  }
}

Location-Based Reminders

Trigger reminders based on location:

{
  "title": "Buy groceries",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 100,           // meters
    "proximity": "enter",    // or "leave"
    "title": "Whole Foods"
  }
}

Multiple Alarms

Add multiple notifications to a reminder:

{
  "title": "Important meeting",
  "dueDate": "2026-01-15T14:00:00Z",
  "alarms": [
    {
      "type": "relative",
      "relativeOffset": -86400  // 1 day before (in seconds)
    },
    {
      "type": "absolute",
      "absoluteDate": "2026-01-15T13:00:00Z"  // 1 hour before
    }
  ]
}

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