Apple Reminders MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with Apple Reminders. Built for use with Claude Desktop, Claude Code, and Claude.ai.

Features

• ✅ 18 Comprehensive Tools - Full CRUD operations for reminders and lists
• 🗣️ Natural Language Dates - Use "tomorrow at 3pm", "next Monday", "in 3 days"
• 🔍 Advanced Search - Filter by completion, priority, flags, text, and more
• 📊 Statistics & Insights - Get overdue reminders, today's tasks, and analytics
• 🎨 List Customization - Set colors and emblems for reminder lists
• 🔌 Dual Transport - Works with both stdio (local) and HTTP (remote) connections
• ⚡ Real-time - Direct integration with your macOS Reminders app

Installation

Prerequisites

• macOS (Apple Reminders is macOS-only)
• Node.js 18.0.0 or higher
• npm or yarn

Quick Install

# Clone the repository
git clone https://github.com/yourusername/apple-reminders-mcp-server
cd apple-reminders-mcp-server

# Install dependencies
npm install

# Start the server
npm start

The server will start on http://localhost:3001 by default.

Configuration

For Claude Desktop/Code (stdio mode)

Add to your Claude Desktop or Claude Code configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["tsx", "/Users/yourusername/Projects/mcp/apple-reminders-mcp-server/src/index.ts"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

For Claude.ai (HTTP mode)

1. Start the server:

   npm start
   

2. In Claude.ai settings, add a new MCP connector:

   • URL: http://localhost:3001/mcp
   • The server includes a health check at http://localhost:3001/health

Available Tools

Reminder Operations

Tool	Description
apple_reminders_create	Create a new reminder with natural language dates
apple_reminders_get	Get reminder details by ID
apple_reminders_update	Update reminder properties
apple_reminders_delete	Delete a reminder
apple_reminders_complete	Mark reminder as complete/incomplete
apple_reminders_move	Move reminder to a different list

Search & Query

Tool	Description
apple_reminders_list	List reminders with filters (completion, priority, etc.)
apple_reminders_search	Search reminders by text
apple_reminders_overdue	Get all overdue reminders
apple_reminders_today	Get reminders due today

List Management

Tool	Description
apple_reminders_list_lists	Get all reminder lists
apple_reminders_get_list	Get specific list details
apple_reminders_create_list	Create a new list with color/emblem
apple_reminders_update_list	Update list properties
apple_reminders_delete_list	Delete a list

Utility

Tool	Description
apple_reminders_accounts	List all accounts (typically iCloud)
apple_reminders_stats	Get statistics and analytics
apple_reminders_show	Open a reminder in the Reminders app

Usage Examples

Creating Reminders

// Simple reminder
{
  "name": "Call mom"
}

// With natural language due date
{
  "name": "Submit report",
  "dueDate": "tomorrow at 5pm",
  "priority": "high",
  "listName": "Work"
}

// With all details
{
  "name": "Doctor appointment",
  "body": "Annual checkup at Main Street clinic",
  "dueDate": "next Monday at 2pm",
  "remindMeDate": "Monday at 1:30pm",
  "priority": "high",
  "flagged": true,
  "listName": "Personal"
}

Searching Reminders

// Find all incomplete tasks
{
  "completed": false
}

// Search for specific text
{
  "query": "meeting",
  "listName": "Work"
}

// Filter by priority
{
  "priority": 1,  // High priority
  "flagged": true
}

Managing Lists

// Create a new list with styling
{
  "name": "Q1 Goals",
  "color": "#30D33B",
  "emblem": "education1"
}

Natural Language Date Examples

The server supports natural language date parsing via chrono-node:

• "tomorrow" → Tomorrow at 00:00
• "tomorrow at 3pm" → Tomorrow at 15:00
• "next Monday" → Next Monday at 00:00
• "in 3 days" → 3 days from now
• "January 15" → January 15 of current/next year
• "2025-01-15" → ISO date format also supported

Known Limitations

Due to AppleScript API limitations, the following features are not supported:

• ❌ Subtasks - Nested/indented reminders are not accessible via AppleScript
• ❌ Tags - Hashtags/tags are not accessible via AppleScript
• ❌ Attachments - Images and file attachments are not accessible
• ❌ Nested Lists - All lists are flat (no folders)

Development

Running in Development Mode

npm run dev

Watch Mode (auto-reload on changes)

npm run watch

Environment Variables

• TRANSPORT - Set to stdio or http (default: http)
• PORT - HTTP server port (default: 3001)
• DEBUG - Enable debug logging
• VERBOSE - Enable verbose logging

Technical Details

Architecture

• Language: TypeScript (run via tsx)
• MCP SDK: @modelcontextprotocol/sdk v1.0.0
• Date Parsing: chrono-node v2.7.0
• Validation: Zod v3.25.0
• HTTP Server: Express v4.18.2

Why tsx instead of compiled JavaScript?

This project uses tsx to run TypeScript directly rather than pre-compiling to JavaScript. This approach:

• Avoids memory issues with complex Zod schema types during TypeScript compilation
• Provides faster development iteration
• Maintains full TypeScript type safety
• Simplifies the build process

File Structure

apple-reminders-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── types.ts              # TypeScript interfaces
│   ├── services/
│   │   ├── applescript.ts    # AppleScript execution
│   │   ├── dateUtils.ts      # Date parsing utilities
│   │   └── reminders.ts      # Reminders business logic
│   ├── schemas/
│   │   └── index.ts          # Zod validation schemas
│   └── tools/
│       └── index.ts          # MCP tool registrations
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

Server won't start

• Ensure Node.js 18+ is installed: node --version
• Check if port 3001 is available: lsof -i :3001
• Verify dependencies are installed: npm install

Reminders app not responding

• Ensure Reminders app has necessary permissions in System Settings > Privacy & Security
• Try manually opening Reminders app first
• Check Console.app for AppleScript errors

Natural language dates not working

• Ensure chrono-node is installed: npm list chrono-node
• Check the date format - some complex natural language may not parse
• Fall back to ISO format if needed: "2025-01-15T15:00:00"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Matthew Grimes

Acknowledgments

• Built on the Model Context Protocol
• Inspired by the Apple Mail MCP Server
• Uses chrono-node for natural language date parsing