Skylight MCP server

skylight-mcp

MCP server for Skylight Calendar — 114 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), photo/video upload, and frame/device/account settings + calendar + member management (read+write, incl. preset and custom-photo avatars).

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 …".

MCP protocol support

The server uses the official TypeScript SDK v2 and supports the stateless 2026-07-28 protocol revision over stdio. Clients can discover and call tools without an initialization handshake. Existing clients can still use the 2025-11-25 handshake.

The transport remains stdio. A host can expose it over authenticated HTTP. This package does not open a network listener.

Auth

The server uses a headless email+password OAuth2 authorization-code flow — no SSO, no 2FA, no browser extension required. Configure it with SKYLIGHTREFRESHTOKEN if you already hold a token, or SKYLIGHTEMAIL + SKYLIGHTPASSWORD to log in for one.

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 — send an S256 PKCE code_challenge (the server requires it) and receive the one-time authorization code via redirect.
4. POST /oauth/token — exchange the code plus the matching codeverifier for a bearer accesstoken + refreshtoken (currently a 24-hour expiry; the client reads the returned expiresin rather than assuming).

OAuth redirects stay on the authentication origin. Relative redirects resolve against the current URL. The configured callback supplies the authorization code without receiving a request or session cookie. Unexpected destinations fail without including the redirect URL in the error.

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 SKYLIGHTFRAMEID to the frame ID you want. Every tool that reads frame-scoped data accepts an optional frameId arg to override the default.

Tools

Shortened. The full README is on GitHub.