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)

create_reminder - Create reminders with comprehensive attributes
- Basic: title, notes, due date, priority, tags, URL
- Advanced: recurring patterns, location triggers, multiple alarms
update_reminder - Update existing reminders
delete_reminder - Permanently delete reminders
complete_reminder - Mark reminder as complete
uncomplete_reminder - Mark reminder as incomplete
get_reminders - List all reminders (filter by completion)

List Management (1 tool)

get_all_lists - Get all reminder lists

Search & Query (5 tools)

search_reminders - Search by text in title/notes
get_todays_reminders - Get reminders due today
get_overdue_reminders - Get past-due reminders
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

Run ./swift-cli/.build/release/reminders-cli request-access
Grant permission in System Settings > Privacy & Security > Reminders
Restart your AI assistant

Swift CLI Not Found

Build the Swift CLI: npm run build:swift
Verify: ls swift-cli/.build/release/reminders-cli

Tool Not Working

Check Swift CLI directly with test JSON
Check MCP server logs in your AI assistant
Use MCP Inspector for isolated debugging

Roadmap

✅ Completed

🔄 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

Built with ❤️ for the MCP ecosystem

Version 0.2.0 | Updated January 2026

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)

create_reminder - Create reminders with comprehensive attributes
- Basic: title, notes, due date, priority, tags, URL
- Advanced: recurring patterns, location triggers, multiple alarms
update_reminder - Update existing reminders
delete_reminder - Permanently delete reminders
complete_reminder - Mark reminder as complete
uncomplete_reminder - Mark reminder as incomplete
get_reminders - List all reminders (filter by completion)

List Management (1 tool)

get_all_lists - Get all reminder lists

Search & Query (5 tools)

search_reminders - Search by text in title/notes
get_todays_reminders - Get reminders due today
get_overdue_reminders - Get past-due reminders
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

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

Run ./swift-cli/.build/release/reminders-cli request-access
Grant permission in System Settings > Privacy & Security > Reminders
Restart your AI assistant

Swift CLI Not Found

Build the Swift CLI: npm run build:swift
Verify: ls swift-cli/.build/release/reminders-cli

Tool Not Working

Check Swift CLI directly with test JSON
Check MCP server logs in your AI assistant
Use MCP Inspector for isolated debugging

Roadmap

✅ Completed

🔄 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

Built with ❤️ for the MCP ecosystem

Version 0.2.0 | Updated January 2026