ai-mcp-garage/mcp-reminders

Apple Reminders MCP Server

A Model Context Protocol (MCP) server for managing Apple Reminders on macOS. Provides full CRUD operations for tasks and projects through a clean, modular architecture.

Features

Read Operations

• list_projects - List all reminder projects with task counts and overdue information
• list_tasks - List all tasks in a specific project with due dates and reminders

Create Operations

• quick_task - Create a quick task in the inbox (default: tomorrow at 9am)
• add_task - Create a detailed task in a specific project with full options
• create_project - Create a new project (reminder list)

Update Operations

• update_task - Update title, notes, due date, or time of existing tasks (by ID only)
• complete_task - Mark a task as completed (by ID only)
• delete_task - Delete a task permanently (by ID only)
• delete_project - Delete a project and all its tasks

Scoped Project Mode

The server supports a scoped project mode for focused project management. Set the PROJECT_NAME environment variable to automatically scope all operations to a specific project:

export PROJECT_NAME="Work"
# Optional: Add project context for better agent understanding
export PROJECT_DESCRIPTION="Engineering tasks and development work"
uv run python server.py

Changes in Scoped Mode:

• Removed tools: list_projects, quick_task, create_project, delete_project
• Simplified signatures: Tools have cleaner parameter lists without project arguments
• Automatic scoping: All operations target the specified project automatically
• Enhanced context: Project description helps agents understand the domain

Quick Examples

Normal Mode

# Create a quick task for tomorrow
quick_task(
    task="Pay the Capital One bill",
    when="tomorrow", 
    time="9am"
)

# Create a detailed task in a specific project
add_task(
    task="Call about work phone reset",
    project="Work",
    due_date="tuesday",
    due_time="noon",
    notes="Contact IT department about phone issues"
)

# List tasks to get IDs
list_tasks(project_name="Work")
# Output shows: • Call about work phone reset [ID: ABC123-DEF456-...]

# Update task by ID (required)
update_task(
    task_id="ABC123-DEF456-GHI789",
    new_due_date="friday",
    new_due_time="2pm"
)

# Complete task by ID (required)
complete_task(task_id="ABC123-DEF456-GHI789")

# Delete task by ID (required)
delete_task(task_id="ABC123-DEF456-GHI789")

# Create and delete projects
create_project(name="New Project")
delete_project(name="Old Project")

Scoped Mode (PROJECT_NAME="Work")

# Clean signatures - no project parameters needed!
add_task(
    task="Review quarterly reports",
    due_date="friday", 
    notes="Focus on Q3 metrics"
)

# List tasks (no project parameter) - shows IDs
list_tasks()
# Output shows: • Review quarterly reports [ID: XYZ789-ABC123-...]

# Update by ID (required) - automatically scoped to Work project
update_task(task_id="XYZ789-ABC123-DEF456", new_due_time="3pm")

# Complete by ID (required)
complete_task(task_id="XYZ789-ABC123-DEF456")

# Delete by ID (required)
delete_task(task_id="XYZ789-ABC123-DEF456")

Date/Time Parsing

The server supports flexible date and time parsing:

Relative Dates:

• today, tomorrow
• monday, tuesday, etc. (next occurrence)
• next week

Times:

• 9am, 2pm (12-hour format)
• 14:30, 09:00 (24-hour format)
• Defaults to 9am if not specified

Installation & Setup

1. Install dependencies:

   uv sync
   

2. Grant Reminders permissions:

   • System Settings → Privacy & Security → Automation
   • Enable Reminders for your terminal/app

3. Run the server:

   # Normal mode
   uv run python server.py
   
   # Scoped mode
   PROJECT_NAME="Work" uv run python server.py
   

MCP Configuration

Normal Mode

{
  "mcpServers": {
    "appleReminders": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-reminders", "python", "server.py"]
    }
  }
}

Scoped Mode

{
  "mcpServers": {
    "appleRemindersWork": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-reminders", "python", "server.py"],
      "env": {
        "PROJECT_NAME": "Work",
        "PROJECT_DESCRIPTION": "Engineering tasks and development work"
      }
    }
  }
}

Architecture

The server is built with a modular architecture:

• server.py - Main server entry point with conditional imports and tool registration
• tools/utils.py - Shared utilities and EventKit setup
• tools/read_tools.py - Read-only operations (normal mode)
• tools/create_tools.py - Task and project creation tools (normal mode)
• tools/modify_tools.py - Update, delete, and complete operations (normal mode)
• tools/scoped_tools.py - Simplified wrappers for scoped project mode

This modular design makes it easy to add new features and maintain clean separation of concerns. The conditional import system provides clean tool signatures in scoped mode while maintaining full flexibility in normal mode.

Task Operations

ID-Based Operations (Required)

All modify operations (update_task, complete_task, delete_task) require task IDs for safe, precise task manipulation:

1. List tasks to see IDs: list_tasks() shows [ID: ABC123-...] for each task
2. Use IDs for operations: complete_task(task_id="ABC123-DEF456-GHI789")

Why ID-Only?

• Safety: No risk of accidentally modifying the wrong task
• Precision: Exact targeting even with duplicate task names
• Reliability: Consistent behavior across all operations
• Automation-friendly: Agents can reliably reference specific tasks

Workflow

1. Run list_tasks() to see available tasks with their IDs
2. Copy the ID from the output: [ID: ABC123-DEF456-GHI789]
3. Use the ID in modify operations: complete_task(task_id="ABC123-DEF456-GHI789")