skylight-mcp

MCP server for Skylight Calendar — 116 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 and 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 — 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 code_verifier for a bearer access_token + refresh_token (currently a 24-hour expiry; the client reads the returned expires_in rather than assuming).

Emailed login code. Skylight may answer step 2 with a 6-digit code sent to the account's email (observed 2026-11-11). The tool call that hit it fails with a message saying so, and skylight_healthcheck reports verification_code_required. Read the email and have the assistant call skylight_submit_login_code with the code (or resend: true for a new one). The login then finishes and the token is cached, so you only need a code again when the cached token is lost — for example after deleting the cache or setting SKYLIGHT_TOKEN_CACHE=false. The open login lives in the running process: restarting the server before you submit the code starts over with a new email.

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.

Using the auth helpers from your own code

The package also exports Skylight's session login and refresh, so a separate program can authenticate without copying src/:

import { login, refresh } from 'skylight-mcp/auth';

const tokens = await login({
  authBaseUrl: 'https://app.ourskylight.com',
  email: process.env.SKYLIGHT_EMAIL!,
  password: process.env.SKYLIGHT_PASSWORD!,
});
// Skylight rotates refresh tokens: store the one each call returns.
const next = await refresh({ authBaseUrl: 'https://app.ourskylight.com', refreshToken: tokens.refreshToken });

This is the only library entry point; everything else in the package is the MCP server. It is ESM-only and ships type declarations.

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.

A supplied refresh token is single-use. Skylight rotates the refresh token every time it is spent, so the server's first start uses up SKYLIGHT_REFRESH_TOKEN and keeps working on the rotated one — which lives only in the token cache. With a token alone, keep that cache enabled and writable, and never share one token between two hosts: a start that finds the env token already spent cannot recover without the login pair.

Optional

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

Photo uploads on a hosted deployment

A hosted server (the claude.ai connector on mcp-host) shares no disk with you, so image_path is refused there and the refusal says what to do instead. The photo tools take exactly one of three sources:

Every route accepts only jpg/jpeg, png, heic, gif, webp, mp4 and mov, and checks the file's leading bytes against its type. The confirmation preview carries the file's SHA-256 and the confirmed call reads the file again, so a file that changed in between is refused (DRAFT_CHANGED). A blob-store upload is deleted once Skylight accepts the photo (the result's blob.deleted says whether the delete worked) and kept if the upload fails, so the same image_blob_key can be retried. skylight_upload_slots is refused on a server with no blob store.

Confirmations

Some writes ask you to confirm before anything happens: uploading a local photo or avatar; inviting, approving or removing a user; deleting a family member; linking an Apple calendar; opening the frame to the public; creating or updating an event with invited_emails (Skylight e-mails each address, and the preview names them); the bulk deletes (skylight_delete_messages, skylight_clear_list, and skylight_delete_list of a non-empty list), whose preview lists every item that would go; and meal/chore edits or deletes whose apply_to reaches past the one occurrence named. A client that can show a confirmation prompt (Claude Code) shows one, unless MCP_CONFIRM_ELICITATION=off. Elsewhere the first call makes no change and returns a preview of exactly what would be sent plus a confirmToken; only a repeat call with that token, and the same arguments, performs it — once.

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. With the login pair that cost is one login. With only SKYLIGHT_REFRESH_TOKEN it would be a lockout, because Skylight rotates that token on first use and the rotated one would never be saved. So a token-only deployment refuses to spend it: SKYLIGHT_TOKEN_CACHE=false without a login pair is a configuration error, and the server checks the cache is writable before the first refresh, failing the call (token unspent) if it is not. A write that fails after that check is reported loudly on stderr.

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.