Pear - iCloud Calendar, Reminders, Contacts & Mail

Pear — iCloud Integration

Pear provides read/write access to iCloud Calendar, Reminders, Contacts, and Mail through 34 MCP tools. All tools are prefixed with pear_ and communicate with iCloud via CalDAV/CardDAV for Calendar, Reminders, and Contacts, plus IMAP/SMTP for Mail.

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
• Read, send, or organize iCloud Mail
• Find free time slots or schedule meetings
• Build a daily briefing from events, reminders, and unread email
• 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"
• "Unread email", "inbox", "send an email", "reply to this email"
• "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)
• 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 (5 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
pear_delete_reminder	Delete a reminder

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 (inline base64 or data:image/... URI)

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

Mail (7 tools)

Tool	Description
pear_list_mail_folders	List mail folders and mailboxes available in iCloud Mail
pear_list_emails	List emails from a folder, with unread and query filters
pear_read_email	Read the full content of an email
pear_send_email	Send an email through iCloud Mail
pear_move_email	Move an email between folders
pear_mark_email_read	Mark an email as read or unread
pear_delete_email	Delete an email by moving it to Trash

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

Mail

• Mail works through iCloud IMAP/SMTP, not through CalDAV/CardDAV
• For Mail to work reliably, the user should onboard Pear with their real @icloud.com address or an iCloud Mail custom-domain address tied to the mailbox
• pear_list_emails is best for inbox scans; use query and unreadOnly to keep results tight
• pear_read_email gives full body content after you identify the message with pear_list_emails
• pear_send_email supports to, cc, bcc, reply headers, and HTML/plain-text bodies

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 inline base64 or data:image/... URIs
• Remote photo URLs are rejected for security reasons

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 does not currently expose a single dedicated briefing tool in the hosted MCP surface. Build daily briefings by combining:

• pear_list_events for the chosen day
• pear_list_reminders for incomplete tasks
• pear_list_emails for unread inbox context when Mail matters

The /pear:briefing command in this plugin already follows that pattern.

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_list_events for today with timezone
→ Call pear_list_reminders for incomplete tasks
→ Optionally call pear_list_emails for unread inbox context
→ Summarize events chronologically, then pending reminders, then important unread mail

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