Skylight

skylight-mcp

MCP server for Skylight Calendar — 102 tools across calendar events (read+write), shared lists (read+write), chores and rewards (read+write), task-box items (read+write), meals (read+write), AI auto-creation (meal-plan + activity-idea generators with draft review/approve), messages and albums (read+write), and frame/device/account settings + calendar + member management (read+write).

Every API request carries the skylight-api-version: 2026-05-01 header (matching the official mobile app); without it some features 422 with "API version does not support …".

Auth

The server uses a headless email+password OAuth2 authorization-code flow — no SSO, no 2FA, no browser extension required. Credentials are always SKYLIGHT_EMAIL + SKYLIGHT_PASSWORD.

On first tool call, the server performs four steps against https://app.ourskylight.com:

1. GET /auth/session/new — fetch the Rails CSRF token and session cookie.
2. POST /auth/session — log in with email + password (must happen before OAuth authorize).
3. GET /oauth/authorize — receive the one-time authorization code via redirect.
4. POST /oauth/token — exchange the code for a bearer access_token + refresh_token (7-day expiry).

The client then refreshes the token proactively (~60 s before expiry) and reactively on any 401. No bot wall has been observed — the headless flow works directly from Node.

No env vars → clean start: if credentials are not set, the server still starts without error. Auth is deferred to the first tool call, so MCP hosts can complete install-time tool listing before credentials are configured.

Frame model

All data in Skylight is scoped to a frame (the family hub device). On first use the client auto-discovers the single frame on the account. If the account has more than one frame, set SKYLIGHT_FRAME_ID to the frame ID you want. Every tool that reads frame-scoped data accepts an optional frameId arg to override the default.

Tools

Module	Tool	R/W	Description
frames	skylight_list_frames	R	List all frames on the account
frames	skylight_get_frame	R	Get details for a specific frame
frames	skylight_list_frame_members	R	List members associated with a frame
frames	skylight_list_devices	R	List physical devices linked to a frame
frames	skylight_get_plus_access	R	Get Skylight Plus subscription / entitlement status
frames	skylight_get_reward_points	R	Get reward-point balances per family member
frames	skylight_get_household_config	R	Get household configuration for the frame
frames	skylight_list_calendars	R	List the frame's calendar accounts and active calendars
frames	skylight_get_event_notification_settings	R	Get the frame's calendar-event notification settings
frames	skylight_resolve_member	R	Resolve a family-member name to its category id
frames	skylight_get_calendar	R	Get one calendar account
frames	skylight_list_nudges	R	List nudges (reminders) in a date range
frames	skylight_update_frame	W	Update frame display/sleep settings
frames	skylight_rename_frame	W	Rename a frame
frames	skylight_update_profile	W	Update the frame profile (name, birthday)
frames	skylight_update_household_config	W	Update household configuration
frames	skylight_set_reminder_profile	W	Set the global reminder cadence (interval_weeks)
frames	skylight_add_webcal	W	Subscribe the frame to a webcal/ICS calendar URL
frames	skylight_update_calendar	W	Set which sub-calendars of a connected account are active
frames	skylight_delete_source_calendar	W	Remove a connected source calendar (incl. webcal subscriptions)
frames	skylight_set_default_calendar	W	Set the default source calendar for new events
frames	skylight_link_apple_calendar	W	Link an Apple/iCloud calendar using an app-specific password
frames	skylight_categorize_source_calendar	W	Attribute a source calendar's events to one or more family members
frames	skylight_create_source_calendar	W	Create a source calendar from raw provider attributes (advanced)
frames	skylight_invite_user	W	Invite a user to the frame by email
frames	skylight_approve_user	W	Approve a pending frame user
frames	skylight_remove_user	W	Remove a user from the frame
frames	skylight_delete_category	W	Delete a category / family member (optional reassign_to_category_id, inferred)