Apple Reminders MCP Server by FradSer - MCP Server

Apple Reminders MCP Server

English |

A Model Context Protocol (MCP) server that provides native integration with Apple Reminders on macOS. This server allows you to interact with Apple Reminders through a standardized interface with comprehensive management capabilities.

Features

Core Functionality

List Management: View all reminders and reminder lists with advanced filtering
Reminder Operations: Create, update, delete, and move reminders across lists
Rich Content: Support for titles, notes, due dates, URLs, and completion status
Native Integration: Seamless integration with macOS Apple Reminders app

Advanced Features

Smart Organization: Automatic categorization by priority, due date, category, or completion status
Powerful Search: Filter reminders by completion status, due dates, and search terms
Batch Operations: Organize multiple reminders with intelligent strategies
Permission Management: Proactive validation of system permissions
Flexible Date Handling: Support for both date-only and date-time formats with locale awareness
Unicode Support: Full international character support with validation

Technical Excellence

Unified API: Streamlined tool architecture with action-based operations
Type Safety: Comprehensive TypeScript coverage with Zod validation
Performance: Swift binaries for performance-critical operations
Error Handling: Consistent error responses with detailed feedback

Prerequisites

Node.js 18 or later
macOS (required for Apple Reminders integration)
Xcode Command Line Tools (required for compiling Swift code)
pnpm (recommended for package management)

Quick Start

Install globally via npm:

npm install -g mcp-server-apple-reminders

Configuration

Configure Cursor

Open Cursor
Open Cursor settings
Click on "MCP" in the sidebar
Click "Add new global MCP server"

Configure the server with the following settings:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "mcp-server-apple-reminders",
      "args": []
    }
  }
}

Configure ChatWise

Open ChatWise
Go to Settings
Navigate to the Tools section
Click the "+" button
Configure the tool with the following settings:
- Type: stdio
- ID: apple-reminders
- Command: mcp-server-apple-reminders
- Args: (leave empty)

Configure Claude Desktop

You need to configure Claude Desktop to recognize the Apple Reminders MCP server. There are two ways to access the configuration:

Option 1: Through Claude Desktop UI

Open Claude Desktop app
Enable Developer Mode from the top-left menu bar
Open Settings and navigate to the Developer Option
Click the Edit Config button to open claude_desktop_config.json

Option 2: Direct File Access

For macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

code %APPDATA%\Claude\claude_desktop_config.json

2. Add Server Configuration

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "mcp-server-apple-reminders",
      "args": []
    }
  }
}

3. Restart Claude Desktop

For the changes to take effect:

Completely quit Claude Desktop (not just close the window)
Start Claude Desktop again
Look for the tool icon to verify the Apple Reminders server is connected

Usage Examples

Once configured, you can ask Claude to interact with your Apple Reminders. Here are some example prompts:

Creating Reminders

Create a reminder to "Buy groceries" for tomorrow at 5 PM.
Add a reminder to "Call mom" with a note "Ask about weekend plans".
Create a reminder in my "Work" list to "Submit report" due next Friday.
Create a reminder with URL "Check this website: https://google.com".

Update Reminders

Update the reminder "Buy groceries" with a new title "Buy organic groceries".
Update "Call mom" reminder to be due today at 6 PM.
Update the reminder "Submit report" and mark it as completed.
Change the notes on "Buy groceries" to "Don't forget milk and eggs".

Managing Reminders

Show me all my reminders.
List all reminders in my "Shopping" list.
Show my completed reminders.

Working with Lists

Show all my reminder lists.
Show reminders from my "Work" list.

The server will:

Process your natural language requests
Interact with Apple's native Reminders app
Return formatted results to Claude
Maintain native integration with macOS

Available MCP Tools

This server provides two unified MCP tools for comprehensive Apple Reminders management:

Reminders Tool

Tool Name: reminders

A comprehensive tool for managing Apple Reminders with action-based operations. Supports all reminder operations through a single unified interface.

Actions: list, create, update, delete, bulk_create, bulk_update, bulk_delete, organize

Parameters by Action

List Action (action: "list"):

list (optional): Name of the reminder list to show
showCompleted (optional): Include completed reminders (default: false)
search (optional): Search term to filter reminders by title or content
dueWithin (optional): Filter by due date range ("today", "tomorrow", "this-week", "overdue", "no-date")

Create Action (action: "create"):

title (required): Title of the reminder
dueDate (optional): Due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'
list (optional): Name of the reminders list to add to
note (optional): Note text to attach to the reminder
url (optional): URL to associate with the reminder

Update Action (action: "update"):

title (required): Current title of the reminder to update
newTitle (optional): New title for the reminder
dueDate (optional): New due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'
note (optional): New note text
completed (optional): Mark reminder as completed/uncompleted
list (optional): Name of the list containing the reminder
url (optional): New URL to attach to the reminder

Delete Action (action: "delete"):

title (required): Title of the reminder to delete
list (optional): Name of the list containing the reminder

Bulk Create Action (action: "bulk_create"):

items (required): Array of reminder objects to create

Bulk Update Action (action: "bulk_update"):

criteria (required): Search criteria to find reminders
updates (required): Properties to update

Bulk Delete Action (action: "bulk_delete"):

criteria (required): Search criteria to find reminders to delete

Organize Action (action: "organize"):

strategy (required): Organization strategy ("priority", "due_date", "category", "completion_status")
sourceList (optional): Source list to organize from
createLists (optional): Create new lists automatically (default: true)

Example Usage

{
  "action": "create",
  "title": "Buy groceries",
  "dueDate": "2024-03-25 18:00:00",
  "list": "Shopping",
  "note": "Don't forget milk and eggs",
  "url": "https://example.com/shopping-list"
}

{
  "action": "list",
  "list": "Work",
  "showCompleted": false,
  "dueWithin": "today"
}

{
  "action": "organize",
  "strategy": "category",
  "sourceList": "Inbox",
  "createLists": true
}

Lists Tool

Tool Name: lists

Manage reminder lists - view existing lists or create new ones for organizing reminders.

Actions: list, create, update, delete

Parameters by Action

List Action (action: "list"):

No additional parameters required

Create Action (action: "create"):

name (required): Name for new reminder list

Update Action (action: "update"):

name (required): Current name of the list to update
newName (required): New name for the reminder list

Delete Action (action: "delete"):

name (required): Name of the list to delete

Example Usage

{
  "action": "create",
  "name": "Project Alpha"
}

Response Formats

Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "Successfully created reminder: Buy groceries"
    }
  ],
  "isError": false
}

Note about URL fields: The url field is currently limited by Apple's EventKit API restrictions and will typically be null. This is a limitation of Apple's EventKit framework, not our implementation. URLs stored in the native URL field of reminders cannot be accessed programmatically.

Structured URL Format: This server now uses a structured format for URLs in reminder notes to ensure consistent parsing and extraction:

Reminder note content here...

URLs:
- https://example.com
- https://another-url.com

URL Extraction: You can extract URLs from reminder notes using the structured format or regex fallback:

// Using the structured format (recommended)
import { extractUrlsFromNotes, parseReminderNote } from './urlHelpers';

// Extract just URLs
const urls = extractUrlsFromNotes(reminder.notes);

// Parse into separate note content and URLs
const { note, urls } = parseReminderNote(reminder.notes);

// Legacy regex method (fallback for unstructured content)
const urlsRegex = reminder.notes?.match(/https?:\/\/[^\s]+/g) || [];

Benefits of Structured Format:

Consistent parsing: URLs are always in a predictable location
Multiple URL support: Handle multiple URLs per reminder reliably
Clean separation: Note content and URLs are clearly separated
Backward compatible: Unstructured URLs still detected as fallback

List Response:

{
  "reminders": [
    {
      "title": "Buy groceries", 
      "list": "Shopping",
      "isCompleted": false,
      "dueDate": "2024-03-25 18:00:00",
      "notes": "Don't forget milk\n\nURLs:\n- https://grocery-store.com\n- https://shopping-list.com",
      "url": null
    }
  ],
  "total": 1,
  "filter": {
    "list": "Shopping",
    "showCompleted": false
  }
}

URL Utilities

The server includes built-in URL utilities for working with the structured URL format. These utilities are exported from src/utils/urlHelpers.js:

Key Functions

extractUrlsFromNotes(notes) - Extract URLs from structured or unstructured notes
parseReminderNote(notes) - Parse notes into separate content and URL array
formatNoteWithUrls(note, urls) - Format note content with structured URLs
removeUrlSections(notes) - Remove URL sections to get clean note content
combineNoteWithUrl(note, url) - Combine note with single URL in structured format

Usage Examples

import { 
  extractUrlsFromNotes, 
  parseReminderNote,
  formatNoteWithUrls 
} from 'mcp-server-apple-reminders/src/utils/urlHelpers.js';

// Extract URLs from any reminder note
const urls = extractUrlsFromNotes(reminder.notes);
console.log(urls); // ['https://example.com', 'https://test.com']

// Parse note into content and URLs
const { note, urls } = parseReminderNote(reminder.notes);
console.log(note); // "Task description" 
console.log(urls); // ['https://example.com']

// Create structured note content
const structured = formatNoteWithUrls("New task", ['https://link1.com', 'https://link2.com']);
// Result: "New task\n\nURLs:\n- https://link1.com\n- https://link2.com"

Organization Strategies

The server provides intelligent reminder organization capabilities through four built-in strategies:

Priority Strategy

Automatically categorizes reminders based on priority keywords:

High Priority: Contains words like "urgent", "important", "critical", "asap"
Medium Priority: Default category for standard reminders
Low Priority: Contains words like "later", "someday", "eventually", "maybe"

Due Date Strategy

Organizes reminders based on their due dates:

Overdue: Past due dates
Today: Due today
Tomorrow: Due tomorrow
This Week: Due within the current week
Next Week: Due next week
Future: Due beyond next week
No Date: Reminders without due dates

Category Strategy

Intelligently categorizes reminders by content analysis:

Work: Business, meetings, projects, office, client related
Personal: Home, family, friends, self-care related
Shopping: Buy, store, purchase, groceries related
Health: Doctor, exercise, medical, fitness, workout related
Finance: Bills, payments, bank, budget related
Travel: Trips, flights, hotels, vacation related
Education: Study, learn, courses, books, research related
Uncategorized: Doesn't match any specific category

Completion Status Strategy

Simple binary organization:

Active: Incomplete reminders
Completed: Finished reminders

Usage Examples

Organize all reminders by priority:

Organize my reminders by priority

Categorize work-related reminders:

Organize reminders from Work list by category

Sort overdue items:

Organize overdue reminders by due date

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines first.

Development

Install dependencies:

npm install

Build the project (TypeScript and Swift binary):

npm run build

Project Structure

.
├── src/                          # Source code directory
│   ├── index.ts                  # Main entry point
│   ├── server/                   # MCP server implementation
│   │   ├── server.ts             # Server configuration and lifecycle
│   │   ├── handlers.ts           # Request handlers and routing
│   │   └── *.test.ts             # Server tests
│   ├── swift/                    # Native Swift integration code
│   │   ├── bin/                  # Compiled Swift binaries
│   │   ├── GetReminders.swift    # Swift source file
│   │   └── build.sh              # Swift build script
│   ├── tools/                    # MCP tool definitions and handlers
│   │   ├── definitions.ts        # Tool schemas and validation
│   │   ├── handlers.ts           # Tool implementation logic
│   │   ├── index.ts              # Tool registration
│   │   └── *.test.ts             # Tool tests
│   ├── types/                    # TypeScript type definitions
│   │   └── index.ts              # Core type definitions
│   ├── utils/                    # Helper functions and utilities
│   │   ├── __mocks__/            # Test mocks
│   │   ├── *.ts                  # Utility modules
│   │   └── *.test.ts             # Utility tests
│   ├── validation/               # Schema validation utilities
│   │   └── schemas.ts            # Zod validation schemas
│   └── test-setup.ts             # Test environment setup
├── dist/                         # Compiled JavaScript output
│   ├── index.js                  # Main compiled entry point
│   ├── swift/bin/                # Compiled Swift binaries
│   ├── server/                   # Server compiled files
│   ├── tools/                    # Tools compiled files
│   ├── types/                    # Types compiled files
│   ├── utils/                    # Utils compiled files
│   └── validation/               # Validation compiled files
├── node_modules/                 # Node.js dependencies
├── package.json                  # Package configuration
├── tsconfig.json                 # TypeScript configuration
├── jest.config.mjs               # Jest test configuration
├── pnpm-lock.yaml               # pnpm lock file
└── *.md                         # Documentation files

Available Scripts

npm run build - Build both TypeScript and Swift components (REQUIRED before starting server)
npm run build:ts - Build TypeScript code only
npm run build:swift - Build Swift binary only
npm run dev - TypeScript development mode with file watching
npm run start - Start the MCP server
npm run test - Run comprehensive test suite
npm run clean - Clean build artifacts