Pear Apple

iCloud Calendar, Reminders & Contacts via Pear. Manage events, reminders, contacts, daily briefings, and AI scheduling. 27 tools for Apple iCloud via CalDAV/...

Security Scan

The skill's description, required API key, and network access are consistent with a third‑party iCloud PIM integration; nothing in the instructions asks for unrelated credentials or system access.

Purpose & Capability

Name/description match the declared requirements: a single PEAR_API_KEY and network access to pearmcp.com are exactly what a Pear iCloud API integration would need. Requested tools (events, reminders, contacts, scheduling) align with the stated purpose.

Instruction Scope

SKILL.md is an instruction-only spec describing calls to Pear's MCP tools and does not instruct the agent to read arbitrary files, other environment variables, or system-wide configuration. It notes that connecting your iCloud account requires an Apple app-specific password, but that is a user-facing Pear setup step rather than an instruction to exfiltrate local secrets.

Install Mechanism

No install spec or bundled code — instruction-only skills are lowest risk because nothing is written to disk or fetched during install.

Credentials

Only PEAR_API_KEY is required, which is proportional to a third-party API integration. However, that single key implicitly grants read/write access to calendars, contacts, and reminders via Pear — treat it as highly sensitive and only provide it to a trusted service.

Persistence & Privilege

always:false (good). The skill can be invoked autonomously by the agent (platform default). Because the API key enables full PIM access, consider limiting autonomous actions or reviewing agent permissions if you don't want unattended changes to calendar/contacts.

Assessment

This skill appears internally consistent, but remember: PEAR_API_KEY is powerful — it permits read/write access to your iCloud calendars, contacts, and reminders via the Pear service. Only install if you trust pearmcp.com and understand Pear's privacy policy. Prefer creating or using limited-scope API keys if Pear supports them, avoid sharing your Apple password (use Pear's dashboard and app-specific passwords for linking), and consider restricting or reviewing agent autonomy so the skill can't make unattended changes. Revoke the API key immediately if you suspect misuse.

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