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

Related MCP server: MCP Apple Reminders

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

Search & Query

List Management

Utility

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