| name | Pear - iCloud Calendar, Reminders, Contacts & Mail |
| description | iCloud Calendar, Reminders, Contacts, and Mail via Pear. Manage events, reminders, contacts, inbox workflows, scheduling, and batch actions. 34 tools for Apple iCloud via CalDAV/CardDAV/IMAP/SMTP. |
| 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, 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_...)
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:
- If the user doesn't specify a calendar, omit
calendarName — Pear auto-selects the default
- For recurring events, use the
recurrence object: { frequency: "WEEKLY", interval: 1, count: 10 }
- For attendees, you can pass names — Pear resolves them against the user's contacts automatically
- Use
idempotencyKey when retrying to prevent duplicate events
- 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 tightpear_read_email gives full body content after you identify the message with pear_list_emailspear_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 daypear_list_reminders for incomplete taskspear_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
