Skip to main content
Glama
icloud-reminders-mcp
by 94youshin

iCloud Reminders MCP

English | 简体中文

icloud-reminders-mcp is a cross-platform Model Context Protocol (MCP) server for Apple Reminders. It uses the maintained pyicloud package and iCloud's CloudKit v2 reminders service, so Windows and Linux machines can manage reminders without macOS, AppleScript, or browser automation.

This is an unofficial iCloud integration. Apple does not publish a stable Reminders API, so an iCloud service change can require a project update.

Capabilities

The server exposes sixteen MCP tools:

Tool

Capability

check_session_status

Check trusted-session and 2FA state

list_reminder_lists

List reminder lists and stable IDs

list_reminders

List active or completed reminders

get_reminder

Read one reminder by ID

create_reminder

Create a reminder, optionally with a parent ID

list_subtasks

List the immediate children of a parent reminder

create_subtask

Create a child task in its parent's list

update_reminder

Change title, notes, due date, priority, flag, or all-day state

set_reminder_completed

Complete or reopen a reminder

get_reminder_recurrence

Read recurrence rules

set_reminder_recurrence

Create or update a daily, weekly, monthly, or yearly rule

clear_reminder_recurrence

Clear recurrence only when confirm=true is supplied

list_reminder_tags

List hashtags attached to a reminder

add_reminder_tag

Add a hashtag idempotently

remove_reminder_tag

Remove a hashtag by ID or exact name

delete_reminder

Delete only when confirm=true is supplied

Additional behavior:

  • Parent/child tasks with dedicated create and list tools

  • Daily, weekly, monthly, and yearly recurrence with interval and occurrence limits

  • Hashtag creation, lookup, and removal

  • Timezone-aware due dates and all-day reminders

  • Beijing time (Asia/Shanghai, UTC+08:00) for all inputs and outputs

  • Apple priority values: 0 none, 1 high, 5 medium, 9 low

  • Exact list-name resolution with stable ID support

  • Mainland China iCloud endpoints

  • Persistent local authentication through pyicloud's keyring/session handling

Related MCP server: MCP Apple Reminders

Requirements

  • Python 3.10 or newer

  • An Apple ID with iCloud Reminders enabled

  • Interactive access for the initial Apple ID password and 2FA login

  • An MCP client that supports stdio servers, such as Codex

Never place an Apple password or 2FA code in source code, MCP configuration, an environment variable, or an issue. Authentication is performed interactively.

Windows installation

Open PowerShell:

git clone https://github.com/94youshin/icloud-reminders-mcp.git
cd icloud-reminders-mcp

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install .

Authenticate interactively:

.\.venv\Scripts\icloud.exe auth login --username "your-apple-id@example.com"

For an Apple account served from mainland China:

.\.venv\Scripts\icloud.exe auth login --username "your-apple-id@example.com" --china-mainland

Linux installation

Install Python's virtual-environment support if your distribution does not already provide it. On Debian or Ubuntu this is typically:

sudo apt-get install python3 python3-venv

Then install the project:

git clone https://github.com/94youshin/icloud-reminders-mcp.git
cd icloud-reminders-mcp

python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install .

Authenticate interactively:

./.venv/bin/icloud auth login --username "your-apple-id@example.com"

Append --china-mainland when required. On a headless Linux host, run the MCP server and the login command as the same OS user. A secure keyring backend is recommended so pyicloud can renew an expired session without storing the Apple password in configuration. Diagnose the active backend with:

./.venv/bin/python -m keyring diagnose

The MCP server can still reuse an already authenticated saved session when no keyring backend is available. A new login or 2FA challenge always requires an interactive terminal. Do not expose the MCP server directly to the public internet.

Run the server

MCP clients normally start the stdio process automatically. It is not a standalone HTTP daemon and should not be registered as a public systemd network service. For a direct smoke test, run the following command; it waits for MCP messages on standard input.

Windows:

.\.venv\Scripts\python.exe -m icloud_reminders_mcp

Linux:

./.venv/bin/python -m icloud_reminders_mcp

Configure Codex on Windows

Add the server to the Codex MCP configuration, using an absolute path:

[mcp_servers.apple-reminders]
command = "C:/path/to/icloud-reminders-mcp/.venv/Scripts/python.exe"
args = ["-m", "icloud_reminders_mcp"]

[mcp_servers.apple-reminders.env]
ICLOUD_USERNAME = "your-apple-id@example.com"
ICLOUD_CHINA_MAINLAND = "false"
ICLOUD_DEFAULT_REMINDER_LIST = "Reminders"

Configure Codex on Linux

[mcp_servers.apple-reminders]
command = "/path/to/icloud-reminders-mcp/.venv/bin/python"
args = ["-m", "icloud_reminders_mcp"]

[mcp_servers.apple-reminders.env]
ICLOUD_USERNAME = "your-apple-id@example.com"
ICLOUD_CHINA_MAINLAND = "false"
ICLOUD_DEFAULT_REMINDER_LIST = "Reminders"

Restart Codex after updating the configuration. The Apple ID username is not a secret, but the password and 2FA code must never be added here.

Environment variables

Variable

Required

Meaning

ICLOUD_USERNAME

Yes

Apple ID username used by the saved session

ICLOUD_CHINA_MAINLAND

No

true to use mainland China endpoints; defaults to false

ICLOUD_DEFAULT_REMINDER_LIST

No

Stable list ID or exact list title used when a tool omits list_id

If multiple lists exist and no default or list_id is supplied, the server fails safely instead of choosing the wrong list.

Example requests

  • "List my Apple reminder lists."

  • "Create an all-day reminder on 31 August in the Work list."

  • "Create a parent task named Release v2, then add these rows as child tasks."

  • "Repeat this reminder every two weeks, for six occurrences."

  • "Add the tags #ReleaseV2 and #InterfaceDesign to this reminder."

  • "Mark reminder REMINDER_ID completed."

  • "Show reminder REMINDER_ID, then ask before deleting it."

For due dates, MCP tools accept ISO 8601 and always normalize values to Beijing time (Asia/Shanghai, UTC+08:00). A timestamp without an offset is interpreted as Beijing time; a timestamp with another offset is converted to Beijing time. For example, 2026-08-31T10:00:00Z becomes 2026-08-31T18:00:00+08:00. Returned timestamps also use +08:00.

Development and tests

Install development dependencies:

python -m pip install -e ".[dev]"
python -m pytest

The test suite covers list selection, ISO date handling, child-task creation, recurrence, hashtags, partial updates, completion, deletion confirmation, and a real stdio MCP initialize/list-tools exchange. Tests use fake iCloud services and do not change the developer's reminders.

Security and limitations

  • pyicloud uses private iCloud web APIs; compatibility is not guaranteed.

  • Saved sessions and credentials remain local and must not be committed.

  • Deletion requires both user approval at the agent layer and confirm=true at the MCP tool layer.

  • Sessions can expire or require fresh 2FA. Stop the MCP process, rerun icloud auth login, and restart the MCP client.

  • Use stable reminder and list IDs when possible; names can be duplicated.

Available Tools

8 tools
check_session_statusA

Check whether the saved iCloud session is trusted or needs 2FA.

Inputs: no named parameters. Returns: object

create_reminderB

Create a reminder or child task using Beijing time (Asia/Shanghai).

Inputs: title (required), due, all_day, flagged, +5 more. Returns: object

delete_reminderA

Delete a reminder. The caller must pass confirm=true after user approval.

Inputs: reminder_id (required), confirm. Returns: object

get_reminderA

Get one reminder by ID with timestamps in Beijing time (+08:00).

Inputs: reminder_id (required). Returns: object

list_reminder_listsA

List Apple Reminder lists and their stable IDs.

Inputs: no named parameters. Returns: result

list_remindersB

List reminders; all returned timestamps use Beijing time (+08:00).

Inputs: limit, list_id, include_completed. Returns: result

set_reminder_completedC

Complete or reopen a reminder using Beijing time for completion.

Inputs: reminder_id (required), completed. Returns: object

update_reminderC

Update supplied fields; due values are normalized to Beijing time.

Inputs: reminder_id (required), due, title, all_day, +4 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct operation: session status, list retrieval, reminder CRUD, and completion state. No two tools overlap in purpose, so an agent can select the correct tool unambiguously.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., create_reminder, list_reminders, delete_reminder). This predictable style makes the set easy to navigate.

    Tool Count5/5

    Eight tools is well-scoped for an iCloud Reminders server, covering essential actions without redundancy. Each tool earns its place, and the count is within the ideal range.

    Completeness5/5

    The set supports full CRUD, completion toggling, list enumeration, and session verification—covering all core reminder workflows. No obvious operations are missing for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers