reminders-blade-mcp 0.2.0

Apple Reminders MCP Server — lists, reminders, search, due dates, create, complete, update

reminders-blade-mcp

Apple Reminders MCP Server — read and manage reminders, lists, due dates, search, create, complete, update, and delete.

Requirements

• macOS 13 (Ventura) or later
• Python 3.12+
• uv package manager
• Reminders permission for your terminal (auto-prompted on first use)

Quick Start

# Install
uv sync

# Run
uv run reminders-blade-mcp

Configuration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "reminders": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/reminders-blade-mcp", "reminders-blade-mcp"],
      "env": {
        "REMINDERS_WRITE_ENABLED": "false"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
REMINDERS_WRITE_ENABLED	false	Enable create/complete/update/delete operations
REMINDERS_MCP_TRANSPORT	stdio	Transport: stdio or http
REMINDERS_MCP_HOST	127.0.0.1	HTTP transport bind address
REMINDERS_MCP_PORT	8771	HTTP transport port

Tools

Read (7)

Tool	Description
reminders_info	System info, access status, list count, write gate
reminders_lists	All reminder lists with counts
reminders_items	Reminders from a list (filter: completed/incomplete)
reminders_item	Single reminder by ID or name
reminders_search	Search by title text across all lists
reminders_due	Due/overdue reminders within N days
reminders_stats	Aggregate stats with per-list breakdown

Write (4) — require REMINDERS_WRITE_ENABLED=true AND confirm=true

Tool	Description
reminders_create	Create a reminder (title, list, due date, priority, notes)
reminders_complete	Mark completed or uncompleted
reminders_update	Update properties (title, due date, priority, notes, flagged)
reminders_delete	Delete a reminder (cannot be undone)

Security

• All user input is escaped to prevent AppleScript injection
• Write operations require both an environment variable gate and per-call confirmation
• Delete operations cannot be undone — double-gated
• Uses /usr/bin/osascript (system binary) to avoid TCC permission churn
• 30-second timeout on all AppleScript executions

Development

make install-dev   # Install with dev dependencies
make check         # Lint + format + type-check
make test          # Unit tests
make test-cov      # Tests with coverage
make test-e2e      # E2E tests (requires Reminders access)

License

MIT