苹果提醒事项
STDIOmacOS苹果提醒事项原生集成MCP服务器
macOS苹果提醒事项原生集成MCP服务器
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.
Install globally via npm:
npm install -g mcp-server-apple-reminders
{ "mcpServers": { "apple-reminders": { "command": "mcp-server-apple-reminders", "args": [] } } }
stdioapple-remindersmcp-server-apple-remindersYou need to configure Claude Desktop to recognize the Apple Reminders MCP server. There are two ways to access the configuration:
claude_desktop_config.jsonFor macOS:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
For Windows:
code %APPDATA%\Claude\claude_desktop_config.json
Add the following configuration to your claude_desktop_config.json:
{ "mcpServers": { "apple-reminders": { "command": "mcp-server-apple-reminders", "args": [] } } }
For the changes to take effect:
Once configured, you can ask Claude to interact with your Apple Reminders. Here are some example prompts:
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 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".
Show me all my reminders.
List all reminders in my "Shopping" list.
Show my completed reminders.
Show all my reminder lists.
Show reminders from my "Work" list.
The server will:
The server ships with a consolidated prompt registry exposed via the MCP ListPrompts and GetPrompt endpoints. Each template shares a mission, context inputs, numbered process, constraints, output format, and quality bar so downstream assistants receive predictable scaffolding instead of brittle free-form examples.
task_category (work, personal, health, shopping, etc.), priority_level (low, medium, high, urgent), and time_frame (today, this week, later this month) inputs produce a same-day execution blueprint that keeps priority work balanced with recovery time. Supports intelligent task clustering, focus block scheduling, and automatic reminder list organization.task_description, optionally context and urgency (low, medium, high, critical), yielding a reminder draft that mitigates follow-through gaps by mapping metadata explicitly.review_type (overdue, completed, upcoming, all) and list_name drive inbox triage scripts that surface stale reminders while avoiding destructive edits.user_ideas (your thoughts and ideas for what you want to accomplish this week) guides a Monday-through-Sunday reset with time blocks tied to existing lists.cleanup_strategy (archive_completed, delete_old, reorganize_lists, merge_duplicates) lists guardrails and sequencing for stress-free list pruning.goal_type (habit, project, learning, health, financial) plus optional time_horizon (daily, weekly, monthly, quarterly, yearly) assemble recurring reminders and reflection cadences.pnpm test -- src/server/prompts.test.ts to assert metadata, schema compatibility, and narrative assembly each time you amend prompt copy.This server provides two unified MCP tools for comprehensive Apple Reminders management:
Tool Name: reminders
A comprehensive tool for managing Apple Reminders with action-based operations. Supports all reminder operations through a single unified interface.
Actions: read, create, update, delete
Main Handler Functions:
handleReadReminders() - Read reminders with filtering optionshandleCreateReminder() - Create new remindershandleUpdateReminder() - Update existing remindershandleDeleteReminder() - Delete remindersRead Action (action: "read"):
id (optional): Unique identifier of a specific reminder to readfilterList (optional): Name of the reminder list to showshowCompleted (optional): Include completed reminders (default: false)search (optional): Search term to filter reminders by title or contentdueWithin (optional): Filter by due date range ("today", "tomorrow", "this-week", "overdue", "no-date")Create Action (action: "create"):
title (required): Title of the reminderdueDate (optional): Due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'targetList (optional): Name of the reminders list to add tonote (optional): Note text to attach to the reminderurl (optional): URL to associate with the reminderUpdate Action (action: "update"):
id (required): Unique identifier of the reminder to updatetitle (optional): New title for the reminderdueDate (optional): New due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'note (optional): New note texturl (optional): New URL to attach to the remindercompleted (optional): Mark reminder as completed/uncompletedtargetList (optional): Name of the list containing the reminderDelete Action (action: "delete"):
id (required): Unique identifier of the reminder to delete{ "action": "create", "title": "Buy groceries", "dueDate": "2024-03-25 18:00:00", "targetList": "Shopping", "note": "Don't forget milk and eggs", "url": "https://example.com/shopping-list" }
{ "action": "read", "filterList": "Work", "showCompleted": false, "dueWithin": "today" }
{ "action": "delete", "id": "reminder-123" }
Tool Name: lists
Manage reminder lists - view existing lists or create new ones for organizing reminders.
Actions: read, create, update, delete
Main Handler Functions:
handleReadReminderLists() - Read all reminder listshandleCreateReminderList() - Create new reminder listshandleUpdateReminderList() - Update existing reminder listshandleDeleteReminderList() - Delete reminder listsRead Action (action: "read"):
Create Action (action: "create"):
name (required): Name for new reminder listUpdate Action (action: "update"):
name (required): Current name of the list to updatenewName (required): New name for the reminder listDelete Action (action: "delete"):
name (required): Name of the list to delete{ "action": "create", "name": "Project Alpha" }
Success Response:
{ "content": [ { "type": "text", "text": "Successfully created reminder: Buy groceries" } ], "isError": false }
Note about URL fields: The url field is fully supported by EventKit API. When you create or update a reminder with a URL parameter, the URL is stored in two places for maximum compatibility:
url property (visible in Reminders app detail view via the "i" icon)Dual Storage Approach:
Reminder note content here...
URLs:
- https://example.com
- https://another-url.com
This ensures URLs are accessible both in the Reminders app UI and through the API/notes for parsing.
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:
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 } }
The server includes built-in URL utilities for working with the structured URL format. These utilities are exported from src/utils/urlHelpers.js:
extractUrlsFromNotes(notes) - Extract URLs from structured or unstructured notesparseReminderNote(notes) - Parse notes into separate content and URL arrayformatNoteWithUrls(note, urls) - Format note content with structured URLsremoveUrlSections(notes) - Remove URL sections to get clean note contentcombineNoteWithUrl(note, url) - Combine note with single URL in structured formatimport { 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"
The server provides intelligent reminder organization capabilities through four built-in strategies:
Automatically categorizes reminders based on priority keywords:
Organizes reminders based on their due dates:
Intelligently categorizes reminders by content analysis:
Simple binary organization:
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
MIT
Contributions welcome! Please read the contributing guidelines first.
pnpm install
pnpm build
pnpm test
pnpm exec biome check
The CLI entry point includes a project-root fallback, so you can start the server from nested paths (for example dist/ or editor task runners) without losing access to the bundled Swift binary. The bootstrapper walks up to ten directories to find package.json; if you customise the folder layout, keep the manifest reachable within that depth to retain the guarantee.
pnpm build - Build the Swift helper binary (required before starting the server)pnpm build:swift - Build the Swift helper binary onlypnpm dev - TypeScript development mode with file watching via tsx (runtime TS execution)pnpm start - Start the MCP server over stdio (auto-fallback to runtime TS if no build)pnpm test - Run the comprehensive Jest test suitepnpm check - Run Biome formatting and TypeScript type checkingRuntime Dependencies:
@modelcontextprotocol/sdk ^1.20.2 - MCP protocol implementationmoment ^2.30.1 - Date/time handling utilitiesexit-on-epipe ^1.0.1 - Graceful process termination handlingtsx ^4.20.6 - TypeScript execution and REPLzod ^4.1.12 - Runtime type validationDevelopment Dependencies:
typescript ^5.9.3 - TypeScript compiler@types/node ^24.9.2 - Node.js type definitions@types/jest ^30.0.0 - Jest type definitionsjest ^30.2.0 - Testing frameworkbabel-jest ^30.2.0 - Babel Jest transformerbabel-plugin-transform-import-meta ^2.3.3 - Babel import meta transformts-jest ^29.4.5 - Jest TypeScript support@biomejs/biome ^2.3.2 - Code formatting and lintingBuild Tools: