Skylight MCP Server

skylight-mcp

MCP server for Skylight Calendar — 111 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 …".

Auth

The server uses a headless email+password OAuth2 authorization-code flow — no SSO, no 2FA, no browser extension required. Configure it with SKYLIGHT_REFRESH_TOKEN if you already hold a token, or SKYLIGHT_EMAIL + SKYLIGHT_PASSWORD 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 — 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

Configuration

Required — one of these two

A refresh token you already hold (preferred: scoped, revocable, and it never touches the rate-limited login endpoint):

SKYLIGHT_REFRESH_TOKEN=your-refresh-token

Or the login pair, which mints one for you:

SKYLIGHT_EMAIL=you@example.com
SKYLIGHT_PASSWORD=your-password

Setting both is also valid, and is the most robust configuration: the token is used first, and if it has expired the login quietly mints a replacement. With a token alone, an expired token is reported as expired — the server says so plainly rather than claiming it is unconfigured.

Optional

Treat .env like a password file — it is gitignored, do not commit it.

Token cache

After the first login the OAuth token pair is cached at $MCP_DATA_DIR/.skylight-mcp/tokens.json (falling back to $HOME), written 0600. A later start reuses it instead of re-running the four-step login — which matters because Skylight's login endpoint rate-limits, and a hosted server that scales to zero cold-starts constantly.

Only the tokens are written; your email and password stay in the environment. A cached token that has expired is refreshed rather than re-logged-in, and a refresh token the server rejects falls back to a fresh login, so a stale file cannot lock you out.

The cache is bound to whichever credential minted it — the password pair, or the supplied SKYLIGHT_REFRESH_TOKEN. Rotate that credential, or point the server at a different account, and the cached token is discarded rather than kept in play. Only a salted digest is stored; no email, password or supplied token reaches the file.

Set SKYLIGHT_TOKEN_CACHE=false to turn it off and log in on every start, or SKYLIGHT_TOKEN_FILE to put the cache somewhere specific.

If a write fails (read-only or full data dir) the server logs to stderr and keeps working on the in-memory token — only the next start pays for it.

Local dev

npm install
npm run build
npm test
npm run dev   # requires .env with credentials

Tests: vitest, 100% line/branch/function/statement coverage enforced. All tests are mocked — no network calls in CI.

Developed and maintained by AI (Claude). Use at your own discretion.