Apple Reminders Integration Service (macOS)

[English] | 中文文档

A high-performance MCP backend engineered to expose the functionality of Apple's native Reminders database via a standardized network protocol. This agent enables external systems to programmatically manage tasks, lists, and scheduling within macOS.

Key Capabilities

Fundamental Operations

• List Inventory: Retrieve comprehensive overviews of all existing reminder containers, supporting granular filtering logic.
• Task Manipulation: Full CRUD (Create, Read, Update, Delete) lifecycle management for individual reminder entries, including cross-list relocation.
• Detail Richness: Full fidelity support for metadata such as task titles, comprehensive notes, precise due/alarm timestamps, associated URLs, and completion state.
• Native Hook-in: Direct, optimized communication path with the underlying macOS Reminders framework.

Advanced Functionality

• Intelligent Sorting: Automated grouping of items based on temporal significance, defined priority levels, assigned categories, or fulfillment status.
• Advanced Querying: Sophisticated retrieval mechanisms allowing filtering by completion status, date boundaries, and keyword matching.
• Bulk Processing: Execution of atomic operations across numerous entries using defined organizational algorithms.
• Security Vetting: Rigorous, upfront validation checks for required system access privileges.
• Localization Support: Robust handling of date and time specifications accommodating various regional formats.
• Internationalization: Complete compatibility with Unicode characters across all input/output fields.

Architectural Strengths

• Cohesive Interface: Simplified tool architecture centered around declarative, action-oriented invocations.
• Data Integrity: Extensive type checking enforced via TypeScript and Zod schemas.
• Execution Speed: Leverages compiled Swift executables for latency-sensitive data pathway operations.
• Reliable Feedback: Standardized, informative error encapsulation for predictable integration.

System Requirements

• Runtime Environment: Node.js LTS version 18 or newer.
• Operating System: macOS (mandatory for interfacing with Reminders).
• Development Toolchain: Xcode Command Line Tools (necessary for compiling embedded Swift components).
• Package Manager: pnpm (recommended for dependency management).

Initial Deployment

Install the CLI utility globally using npm:

bash npm install -g mcp-server-apple-reminders

Integration Instructions

Configuring in Cursor IDE

1. Launch the Cursor application.
2. Access application Settings.
3. Select the 'MCP' section from the navigation panel.
4. Initiate the process to 'Add new global MCP server'.

5. Configure the agent using these parameters:

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

Configuring in ChatWise

1. Open ChatWise and navigate to its configuration interface.
2. Locate the 'Tools' management area.
3. Use the addition control ('+') to define a new tool.
4. Set the configuration profile:
   • Method: stdio
   • Identifier: apple-reminders
   • Execution Path: mcp-server-apple-reminders
   • Arguments: (Empty)

Configuring in Claude Desktop

Integration requires registering the agent within the Claude Desktop configuration file. Access is available via two methods:

Method A: Via Application Menu

1. Start Claude Desktop.
2. Activate Developer Mode via the top menu bar options.
3. Navigate to Settings -> Developer Options.
4. Click 'Edit Config' to open claude_desktop_config.json.

Method B: Direct File Access

Access the configuration file directly using your preferred editor (e.g., VS Code):

• macOS Path: bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Injecting Agent Configuration

Insert the following block into your configuration file (claude_desktop_config.json):

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

Step 3: Activation and Verification

Ensure configuration persistence by performing a full shutdown and restart of Claude Desktop.

1. Exit Claude Desktop completely (ensure no background processes remain).
2. Relaunch the application.
3. Confirm the presence of the associated tool indicator, signifying successful connection.

Interaction Examples

Upon successful setup, direct Claude to manage your tasks using natural language:

Task Creation Prompts

Schedule a task: "Purchase supplies" for 5 PM tomorrow. Log a new item: "Contact Smith Co." with the annotation: "Discuss Q3 projections". Establish a task in the 'Professional' container labeled "Finalize Budget Draft" due end of next week. Define a task entry containing the web reference: "Review documentation at https://docs.example.org".

Task Modification Prompts

Rename the entry "Purchase supplies" to "Procure necessary materials". Reschedule "Contact Smith Co." to be due this evening at 19:00. Mark the "Finalize Budget Draft" task as completed. Revise the commentary on "Procure necessary materials" to include specific item locations.

Task Retrieval Prompts

Display the complete roster of all outstanding reminders. Retrieve all items nested within the 'Errands' list. Isolate and present only the tasks marked as fulfilled.

List Management Prompts

Enumerate all defined reminder lists. Fetch entries belonging exclusively to the 'Projects' container.

The agent's operational flow: - Interprets conversational input. - Executes system calls against the native Reminders service. - Formats and returns operational outcomes to the calling LLM. - Guarantees persistent, accurate synchronization with macOS state.

Exposed MCP Tools

This service exposes two primary interfaces conforming to the MCP specification for comprehensive task administration:

Tool Identifier: reminders

This singular utility encapsulates all operations related to individual task entries, utilizing action verbs for command specification.

Available Verbs: list, create, update, delete, bulk_create, bulk_update, bulk_delete, organize

Verb Parameter Schemas

list Verb (action: "list"): * list (Optional): Container name for filtering. * showCompleted (Optional): Boolean flag to include fulfilled items (Default: false). * search (Optional): Text string used for substring matching in titles/content. * dueWithin (Optional): Temporal scope filter ("today", "tomorrow", "this-week", "overdue", "no-date").

create Verb (action: "create"): * title (Mandatory): The task's descriptive title. * dueDate (Optional): Target date/time string ('YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'). * list (Optional): Destination container name. * note (Optional): Auxiliary descriptive text. * url (Optional): Associated hyperlink reference.

update Verb (action: "update"): * title (Mandatory): The existing title used to locate the entry. * newTitle (Optional): Replacement title. * dueDate (Optional): New target date/time. * note (Optional): Revised auxiliary text. * completed (Optional): Boolean to toggle fulfillment status. * list (Optional): Name of the current container holding the entry. * url (Optional): Replacement hyperlink.

delete Verb (action: "delete"): * title (Mandatory): Title of the item targeted for removal. * list (Optional): Container name for precise deletion scope.

bulk_create Verb (action: "bulk_create"): * items (Mandatory): Array structure containing objects for mass entry generation.

bulk_update Verb (action: "bulk_update"): * criteria (Mandatory): Set of selectors to identify targets. * updates (Mandatory): Map defining properties to modify.

bulk_delete Verb (action: "bulk_delete"): * criteria (Mandatory): Selection logic to identify targets for deletion.

organize Verb (action: "organize"): * strategy (Mandatory): The algorithmic approach to sorting ("priority", "due_date", "category", "completion_status"). * sourceList (Optional): The container from which reorganization occurs. * createLists (Optional): Flag to permit the creation of new categories/lists (Default: true).

Illustrative Command Structure

{ "action": "create", "title": "Secure payment", "dueDate": "2024-10-15 10:30:00", "list": "Finance", "note": "Pay electricity bill.", "url": "https://utility.example.net" }

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

{ "action": "organize", "strategy": "due_date", "sourceList": "Inbox", "createLists": false }

Tool Identifier: lists

This utility focuses exclusively on the administration of reminder list containers (e.g., creating new organizational folders).

Available Verbs: list, create, update, delete

Verb Parameter Schemas

list Verb (action: "list"): * Requires no parameters.

create Verb (action: "create"): * name (Mandatory): Desired identifier for the new container.

update Verb (action: "update"): * name (Mandatory): The existing identifier of the container. * newName (Mandatory): The replacement identifier for the container.

delete Verb (action: "delete"): * name (Mandatory): Identifier of the container to be erased.

Illustrative List Command

{ "action": "create", "name": "Travel Plans" }

Response Structure

Successful Operation Response:

{ "content": [ { "type": "text", "text": "Task 'Secure payment' registered successfully." } ], "isError": false }

Critical Note on URL Fields: Due to limitations within Apple's EventKit API interfacing, the dedicated url attribute within native reminders remains inaccessible programmatically and will consistently report null.

Recommended URL Handling (Structured Notes): To ensure reliable persistence and retrieval of external links, this service mandates a specific note formatting convention:

Standard note content here...

URLs: - https://primary-resource.org - https://secondary-resource.net

Extraction Logic: URLs can be parsed using the recommended structure parser or as a fallback, via traditional regular expression matching: typescript // Recommended parsing utility import import { parseReminderNote } from './urlHelpers';

// Deconstructs notes into clean text and an array of URLs const { note, urls } = parseReminderNote(reminder.notes);

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

Advantages of Structured Formatting: * Predictable location for URL data. * Robust support for multiple associated links. * Clear segregation between descriptive text and reference data. * Maintains backward compatibility for legacy entries.

Example List Response Structure:

{ "reminders": [ { "title": "Secure payment", "list": "Finance", "isCompleted": false, "dueDate": "2024-10-15 10:30:00", "notes": "Pay electricity bill.\n\nURLs:\n- https://utility.example.net", "url": null } ], "total": 1, "filter": { "list": "Finance", "showCompleted": false } }

URL Management Utilities

Internal helper functions, accessible via src/utils/urlHelpers.js, simplify working with the structured URL note format.

Core Exported Functions

• extractUrlsFromNotes(notes) - Pulls all URLs (structured or embedded) from a note string.
• parseReminderNote(notes) - Separates note content from the structured URL block.
• formatNoteWithUrls(note, urls) - Reassembles note content with the standardized URL footer.
• removeUrlSections(notes) - Strips the URL footer to obtain pure user description.
• combineNoteWithUrl(note, url) - Merges a single new URL into the structured footer.

Implementation Snippet

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

// Clean retrieval of associated links const { note, urls } = parseReminderNote(rawNoteContent);

// Formatting a fresh note with links const finalizedText = formatNoteWithUrls("New action item", ['https://project-link.org']); // Result: "New action item\n\nURLs:\n- https://project-link.org"

Organizational Heuristics

The service implements four distinct, automated strategies for arranging reminder items:

1. Priority Heuristic

Applies categorization based on semantic keywords within the task title or notes: * High Urgency: Keywords like "critical", "immediate", "must-do". * Standard: Default classification for non-tagged items. * Deferred: Keywords such as "eventually", "when time permits", "low importance".

2. Temporal Ordering Heuristic

Sorts items based on their scheduled completion date: * Missed Deadline: Items past their due date. * Today: Due within the current 24-hour window. * Next Day: Due tomorrow. * Current Week: Due by the upcoming weekend. * Upcoming: Due beyond the next seven days. * Unscheduled: Lacks any date/time assignment.

3. Content Categorization Heuristic

Employs basic text analysis to assign predefined system categories: * Business: Keywords relating to work, administration, corporate entities. * Private: Keywords related to personal life, family, recreation. * Procurement: Keywords related to purchasing, stores, requisitions. * Wellness: Keywords concerning fitness, medical appointments, diet. * Fiscal: Keywords related to budgeting, invoices, financial tracking. * Transit: Keywords related to itineraries, journeys, accommodations. * Academic: Keywords involving study, coursework, instruction. * Unclassified: Items not matching defined patterns.

4. Status Segregation Heuristic

Simple binary partitioning: * Active: Pending completion. * Fulfilled: Marked as complete.

Usage Examples for Organization

Execute sorting across all items by urgency level:

Apply the priority sorting logic across my entire task database.

Move items flagged as urgent from the 'Client' list:

Reorder tasks within the 'Client' list based on their due dates.

Licensing

Distributed under the MIT License.

Developer Collaboration

We encourage community contributions! Review the contribution guidelines before submitting pull requests.

Development Workflow

1. Install required assets: bash npm install

2. Compile source assets (TypeScript and native Swift binaries): bash npm run build

Directory Map

. ├── src/ # Primary source code repository │ ├── index.ts # Bootstrap script │ ├── server/ # MCP Server Core Logic │ │ ├── server.ts # Configuration and process management │ │ ├── handlers.ts # Request dispatch and processing routines │ │ └── .test.ts # Unit tests for server components │ ├── swift/ # Native macOS bridging code │ │ ├── bin/ # Output directory for compiled executables │ │ ├── BridgeCode.swift # Core Swift integration file │ │ └── build_script.sh # Shell script for Swift compilation │ ├── tools/ # MCP Tool Definitions │ │ ├── schemas.ts # Tool interfaces and validation contracts │ │ ├── implementation.ts # Business logic for tool actions │ │ ├── index.ts # Tool registration point │ │ └── .test.ts # Tool logic validation │ ├── types/ # Data structure definitions │ │ └── index.ts # Global type exports │ ├── utils/ # Shared utility modules │ │ ├── mocks/ # Test environment fixtures │ │ └── .ts # Utility implementations │ ├── validation/ # Data integrity checks │ │ └── schemas.ts # Zod validation schemas definitions │ └── test-setup.ts # Test environment bootstrapping ├── dist/ # Production output directory │ ├── index.js # Compiled main application file │ ├── server/ # Compiled server modules │ ├── tools/ # Compiled tool modules │ └── ... # Other compiled assets ├── node_modules/ # Third-party packages ├── package.json # Project manifest ├── tsconfig.json # TypeScript compilation settings ├── jest.config.mjs # Testing suite configuration ├── pnpm-lock.yaml # pnpm dependency resolution ledger └── .md # Documentation files

Available CLI Commands

• npm run build - Executes full compilation (TS + Swift).
• npm run build:ts - Compiles TypeScript sources only.
• npm run build:swift - Executes native Swift compilation exclusively.
• npm run dev - Initiates TypeScript in watch mode for rapid iteration.
• npm run start - Launches the MCP gateway service.
• npm run test - Runs the complete suite of automated verification checks.
• npm run clean - Removes all generated artifacts from dist/ and build/.

Core Dependencies

Operational Dependencies: * @modelcontextprotocol/sdk ^1.5.0 - Core MCP SDK interface. * moment ^2.30.1 - Essential for time arithmetic and formatting. * zod ^3.24.2 - Library for runtime data schema validation.

Development Dependencies: * typescript ^5.8.2 - Language compiler. * @types/node ^20.0.0 - Node environment type declarations. * jest ^29.7.0 - Unit and integration testing framework. * ts-jest ^29.1.2 - Adapter for running TypeScript tests via Jest.

Build Dependencies: * Native Swift executables. * TypeScript compilation pipeline.