Pear MCP iCloud Calendar, Reminders & Contacts

---

name: Pear - iCloud Calendar, Reminders & Contacts description: iCloud Calendar, Reminders & Contacts via Pear. Manage events, reminders, contacts, daily briefings, and AI scheduling. 27 tools for Apple iCloud via CalDAV/CardDAV. homepage: https://pearmcp.com metadata: openclaw: emoji: "🍐" primaryEnv: PEAR_API_KEY requires: env: - PEAR_API_KEY network: - pearmcp.com

---

Pear — iCloud Integration

Pear provides read/write access to iCloud Calendar, Reminders, and Contacts through 27 MCP tools. All tools are prefixed with pear_ and communicate with iCloud via CalDAV/CardDAV protocols.

When to Use

Activate this skill when the user wants to:

Check their schedule, upcoming events, or daily agenda

Create, update, or delete calendar events

Manage reminders or to-do lists

Look up, create, or update contacts

Find free time slots or schedule meetings

Get a daily briefing of events and tasks

Check availability for a specific time

Work with contact groups

Perform bulk operations on events, reminders, or contacts

Activation triggers:

"What's on my calendar", "my schedule", "upcoming events"

"Remind me to", "add a reminder", "my tasks", "to-do"

"Find contact", "add a contact", "phone number for"

"Schedule a meeting", "find a time", "when am I free"

"Daily briefing", "what's today look like"

"Birthday", "anniversaries"

Do NOT activate for:

Apple Notes (not supported — CalDAV only)

Apple Mail or iMessage

iCloud Drive or file storage

Apple Music, Photos, or other non-PIM services

Local macOS Calendar.app scripting (Pear works cross-platform via API)

Prerequisites

Required Environment Variable:

PEAR_API_KEY — Your Pear API key (format: pear_sk_...)

- Sign up at pearmcp.com - Generate an API key from the dashboard - Connect your iCloud account (requires an app-specific password)

Optional:

PEAR_MCP_URL — Custom endpoint URL (defaults to https://pearmcp.com/api/mcp)

Tool Reference

Events (8 tools)

| Tool | Description | |------|-------------| | pear_list_calendars | List all iCloud calendars (including read-only subscriptions) | | pear_list_events | List events in a time range, with pagination and calendar filtering | | pear_search_events | Search events by title or description within a date range | | pear_create_event | Create an event with optional recurrence, alarms, attendees, and location | | pear_update_event | Update an existing event's properties | | pear_delete_event | Delete an event by filename | | pear_find_free_slots | Find available time slots of a given duration | | pear_check_availability | Check if a specific time slot is free, returns conflicts |

Reminders (4 tools)

| Tool | Description | |------|-------------| | pear_list_reminders | List reminders with optional list filtering, includes completed toggle | | pear_create_reminder | Create a reminder with optional due date, priority (1=high, 5=med, 9=low), and notes | | pear_update_reminder | Update a reminder's properties | | pear_complete_reminder | Mark a reminder as completed |

Contacts (9 tools)

| Tool | Description | |------|-------------| | pear_list_contacts | List all contacts with full vCard data (phones, emails, addresses, birthdays) | | pear_search_contacts | Search by name, email, phone, or organization | | pear_create_contact | Create a contact with full vCard support including photo | | pear_update_contact | Update contact fields (merges with existing data) | | pear_delete_contact | Delete a contact | | pear_list_contact_groups | List all contact groups with member counts | | pear_create_contact_group | Create a new contact group | | pear_add_contact_to_group | Add a contact to a group by name or email | | pear_update_contact_photo | Update a contact's photo (Base64, data URI, or external URL) |

Briefing (1 tool)

| Tool | Description | |------|-------------| | pear_get_daily_briefing | Get today's events and pending reminders in one call. Enriches attendees with contact data. |

Scheduling (1 tool)

| Tool | Description | |------|-------------| | pear_find_best_time | AI-scored optimal meeting slots. Considers work hours, time-of-day preference, day-of-week preference, buffer time, and reminder deadlines. |

Batch Operations (4 tools)

| Tool | Description | |------|-------------| | pear_create_events_batch | Create up to 50 events in one call | | pear_create_reminders_batch | Create up to 50 reminders in one call | | pear_create_contacts_batch | Create up to 50 contacts in one call | | pear_delete_contacts_batch | Delete up to 50 contacts in one call |

Workflow Guidelines

Dates and Times

Always use ISO 8601 format: 2025-06-15T14:30:00Z or 2025-06-15T14:30:00+10:00

Timezone parameter: Pass timezone (IANA format like America/New_York or Australia/Sydney) for user-friendly display times

All-day events: Set isAllDay: true and use date-only format 2025-06-15

Date ranges: pear_list_events requires a timeRange object: { start: "...", end: "..." }

Creating Events

When creating events, follow this pattern:

1. If the user doesn't specify a calendar, omit calendarName — Pear auto-selects the default 2. For recurring events, use the recurrence object: { frequency: "WEEKLY", interval: 1, count: 10 } 3. For attendees, you can pass names — Pear resolves them against the user's contacts automatically 4. Use idempotencyKey when retrying to prevent duplicate events 5. Alarms use minutes before: { action: "display", trigger: 15 } for a 15-minute reminder

Finding Meeting Times

For scheduling, prefer pear_find_best_time over pear_find_free_slots:

pear_find_best_time returns AI-scored slots considering work hours, preferences, and existing commitments

Pass preferences to customize: { timeOfDay: "morning", focusTime: true, workHoursStart: 9, workHoursEnd: 17 }

pear_find_free_slots is simpler — just returns raw available slots without scoring

Reminders

Reminders are accessed via CalDAV (VTODO protocol) — basic operations work well (title, due date, priority, notes, completion). Modern Apple Reminders features like subtasks, tags, smart lists, and location-based reminders are not available via CalDAV.

Priority values: 1 = high, 5 = medium, 9 = low, 0 = none

To list only incomplete reminders, use includeCompleted: false (default)

Reminder lists are auto-created if they don't exist when using listName

Contacts

pear_update_contact merges fields — it won't erase data you don't include in the update

Birthday format: YYYY-MM-DD for full date, --MM-DD for year-unknown

Phone/email can be a single string or an array for multiple entries

Contact photos accept Base64 or data URI format

Virtual Birthdays

Pear generates all-day birthday events from contact birthday fields. These appear as events on a "Birthdays" calendar when listing events. This is a synthesized feature — Apple's native Birthdays calendar is not exposed via CalDAV.

Daily Briefing

pear_get_daily_briefing is the most efficient way to give the user an overview:

Returns today's events + pending reminders in a single call

Automatically enriches event attendees with contact details (name, email, phone)

Pass timezone for correct day boundaries

Pass date to get a briefing for a different day

Safety & Confirmation

Actions Requiring Care

| Action | Risk | Guidance | |--------|------|----------| | pear_delete_event | Removes event permanently | Confirm event title and date with user before deleting | | pear_delete_contact | Removes contact permanently | Always confirm — show contact name first | | pear_delete_contacts_batch | Bulk delete up to 50 contacts | Require explicit user confirmation with count | | pear_update_event | Overwrites event fields | Summarize changes before applying | | pear_complete_reminder | Marks as done | Safe — can be undone by updating completed: false | | Batch create operations | Creates up to 50 items | Confirm count and summarize before executing |

Data Safety

Read operations are always safe — listing, searching, and briefings have no side effects

Updates merge, not replace — pear_update_contact preserves fields you don't mention

Batch operations are rate-limited — chunks of 5 with 200ms delays, no need to throttle manually

Never expose the user's PEAR_API_KEY — treat it as a secret

Error Handling

| Error Code | Meaning | What to Do | |------------|---------|------------| | -32001 | Missing or invalid API key | Check PEAR_API_KEY is set correctly | | -32602 | Invalid parameters | Check parameter names and types against tool reference | | -32603 | Server error | Retry once, then report to user | | 404 on event/reminder | Item not found | The filename may have changed — re-list to get current filenames | | Calendar is read-only | Cannot modify subscription calendars | List calendars first to check which are writable |

Common Patterns

Error Recovery (Idempotency)

Event creation failed mid-request or timed out:
→ Retry pear_create_event with the same idempotencyKey
→ Pear deduplicates — no double-booking even if the first request succeeded silently

Morning Briefing

User: "What's on my plate today?"
→ Call pear_get_daily_briefing with timezone
→ Summarize events chronologically, then pending reminders

Schedule a Meeting

User: "Find time for a 1-hour meeting this week"
→ Call pear_find_best_time with durationMinutes: 60 and this week's range
→ Present top 3 options with scores
→ On user selection, call pear_create_event

Quick Reminder

User: "Remind me to call the dentist tomorrow"
→ Call pear_create_reminder with title and dueDate set to tomorrow

Contact Lookup

User: "What's Sarah's phone number?"
→ Call pear_search_contacts with query: "Sarah"
→ Return matching contacts with phone numbers

Bulk Event Creation

User: "Add these 5 meetings to my calendar"
→ Call pear_create_events_batch with all events in one request
→ Summarize results (created count, any failures)

References

Pear Documentation

Apple App-Specific Passwords

CalDAV Protocol (RFC 4791)

CardDAV Protocol (RFC 6352)

IANA Timezone Database

Required Environment Variable:

PEAR_API_KEY — Your Pear API key (format: pear_sk_...)

- Sign up at pearmcp.com - Generate an API key from the dashboard - Connect your iCloud account (requires an app-specific password)

Optional:

PEAR_MCP_URL — Custom endpoint URL (defaults to https://pearmcp.com/api/mcp)