Skylight MCP Server

An MCP (Model Context Protocol) server for the Skylight Calendar API. Enables AI assistants like Claude to interact with your Skylight family calendar, chores, lists, and more.

Note: This is a maintained continuation of TheEagleByte/skylight-mcp. The original project appears unmaintained; this repo carries the project forward with ongoing updates and bug fixes. The full original commit history and authorship is preserved in git.

Features

• Calendar: Query calendar events ("What's on my calendar today?")
• Chores: View and create chores ("Add emptying dishwasher to chores")
• Lists: View grocery and to-do lists ("What's on the grocery list?")
• Tasks: Add items to the task box ("Add XYZ to my task list")
• Family: View family members and devices
• Rewards: Check reward points and available rewards

Quick Start

Installation

Option 1: Claude Desktop (.mcpb, easiest)

1. Download the latest skylight-mcp-<version>.mcpb from the Releases page.
2. In Claude Desktop, open Settings → Extensions, click Advanced settings, find the Extension Developer section, and click Install Extension…. Select the downloaded .mcpb. (On macOS/Windows, double-clicking the .mcpb file may also trigger the installer.)
3. Fill in your Skylight email, password, frame ID, and timezone when prompted.
4. That's it — the Skylight tools are available in Claude Desktop.

No Node.js install or config editing required. Credentials are stored securely by Claude Desktop.

Option 2: npm package

mcp.json:

{
  "mcpServers": {
    "skylight": {
      "command": "npx",
      "args": ["@rjhalvorson/skylight-mcp"],
      "env": {
        "SKYLIGHT_EMAIL": "[email protected]",
        "SKYLIGHT_PASSWORD": "your_password",
        "SKYLIGHT_FRAME_ID": "your_frame_id"
      }
    }
  }
}

Claude Code:

claude mcp add skylight npx @rjhalvorson/skylight-mcp \
  -e [email protected] \
  -e SKYLIGHT_PASSWORD=your_password \
  -e SKYLIGHT_FRAME_ID=your_frame_id

Option 3: From source

git clone https://github.com/rjhalvorson/skylight-mcp.git
cd skylight-mcp && npm install && npm run build

Then use in mcp.json:

{
  "mcpServers": {
    "skylight": {
      "command": "node",
      "args": ["/path/to/skylight-mcp/dist/index.js"],
      "env": {
        "SKYLIGHT_EMAIL": "[email protected]",
        "SKYLIGHT_PASSWORD": "your_password",
        "SKYLIGHT_FRAME_ID": "your_frame_id"
      }
    }
  }
}

Instructions for AI

Copy this into your AI's custom instructions or system prompt:

You have access to the Skylight MCP server. Skylight is a smart family calendar display that shows calendars, chores, grocery lists, meals, and rewards. Use the Skylight tools to help manage family schedules and organization.

Tips:

• Call get_family_members before assigning chores to get member names
• Grocery items default to the main grocery list if no list specified
• Dates accept "today", "tomorrow", day names, or YYYY-MM-DD format
• Some tools (rewards, meals, photos) require Skylight Plus subscription

Prerequisites

• Node.js 20+
• A Skylight account with an active subscription
• Your Skylight Frame ID (see Finding your Frame ID)

Authentication

The MCP server supports two authentication methods:

Option 1: Email/Password (Recommended)

Use your Skylight account credentials. The server automatically follows Skylight's web OAuth login flow and manages the returned bearer token for you.

[email protected]
SKYLIGHT_PASSWORD=your_password
SKYLIGHT_FRAME_ID=your_frame_id

Option 2: Manual Token (Legacy)

Capture a bearer or basic token from Skylight traffic using a proxy tool.

SKYLIGHT_TOKEN=your_token_here
SKYLIGHT_FRAME_ID=your_frame_id
SKYLIGHT_AUTH_TYPE=bearer

Finding your Frame ID

You still need to find your frame ID (the household identifier):

1. Use a proxy tool (Proxyman, Charles, or mitmproxy)
2. Capture any API request from the Skylight app
3. Look at the URL path: /api/frames/{frameId}/...
4. Example: /api/frames/abc123/chores → frame ID is abc123

Configuration

| Variable | Required | Description | |----------|----------|-------------| | SKYLIGHT_EMAIL | Option 1 | Your Skylight account email | | SKYLIGHT_PASSWORD | Option 1 | Your Skylight account password | | SKYLIGHT_TOKEN | Option 2 | Your captured API token (if not using email/password) | | SKYLIGHT_AUTH_TYPE | No | bearer (default) or basic (for manual token) | | SKYLIGHT_FRAME_ID | Yes | Your household frame ID | | SKYLIGHT_TIMEZONE | No | Default timezone (default: America/New_York) |

Auth Notes

• Email/password auth no longer uses the legacy /api/sessions token flow.
• The server now reproduces the Skylight web login flow and exchanges the resulting authorization code for a bearer token.
• Manual token auth still works if you prefer to provide a captured token directly.

Example .env file:

# Email/password auth (recommended)
[email protected]
SKYLIGHT_PASSWORD=your_password
SKYLIGHT_FRAME_ID=your_frame_id
SKYLIGHT_TIMEZONE=America/New_York

Available Tools

Calendar Tools

| Tool | Description | |------|-------------| | get_calendar_events | Get calendar events for a date range | | get_source_calendars | List connected calendar sources (Google, iCloud, etc.) |

Chore Tools

| Tool | Description | |------|-------------| | get_chores | Get chores with optional filters (date, assignee, status) | | create_chore | Create a new chore with optional recurrence |

List Tools

| Tool | Description | |------|-------------| | get_lists | Get all available lists | | get_list_items | Get items from a specific list |

Task Tools

| Tool | Description | |------|-------------| | create_task | Add a task to the task box |

Family Tools

| Tool | Description | |------|-------------| | get_family_members | Get family member profiles | | get_frame_info | Get household/frame information | | get_devices | List Skylight devices |

Reward Tools

| Tool | Description | |------|-------------| | get_rewards | Get available rewards | | get_reward_points | Get reward points balance |

Example Queries

Once configured, you can ask Claude things like:

• "What's on my calendar today?"
• "What chores do I need to do this week?"
• "Add 'take out trash' to my chores for tomorrow"
• "What's on the grocery list?"
• "Add milk to my task list"
• "Who are the family members on Skylight?"
• "How many reward points does each person have?"

Development

# Run in development mode (with hot reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

API Documentation

This MCP server is built on top of the reverse-engineered Skylight API. The API endpoints are documented in the upstream skylight-api project (maintained separately by TheEagleByte), which converts browser network traffic (HAR files) into an OpenAPI specification.

Upstream API Resources (hosted by the skylight-api project):

• Interactive API Docs (Swagger UI)
• API Reference (ReDoc)
• OpenAPI Specification

If you discover new API endpoints or find issues with the API documentation itself, please contribute to the upstream skylight-api repository. For MCP server issues, use this repo's issue tracker.

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository and create a feature branch
2. Make your changes with clear, descriptive commits
3. Run tests (npm test) and linting (npm run lint) before submitting
4. Open a pull request with a description of your changes

Development Setup

git clone https://github.com/rjhalvorson/skylight-mcp.git
cd skylight-mcp
npm install
npm run dev  # Start with hot reload

Areas for Contribution

• Adding support for new Skylight API endpoints
• Improving error handling and edge cases
• Enhancing documentation
• Writing additional tests

Security & Privacy

When you install the .mcpb in Claude Desktop, you'll see a warning that the extension "can view everything on your computer." This is a blanket warning Claude Desktop shows for every locally-installed MCP server, regardless of what the server actually does. MCP servers run as ordinary Node.js processes with the same access as any program you launch.

What this server actually accesses:

• Reads the environment variables you configure (SKYLIGHT_EMAIL, SKYLIGHT_PASSWORD, SKYLIGHT_FRAME_ID, SKYLIGHT_TIMEZONE, or SKYLIGHT_TOKEN).
• Reads its own package.json at startup to report the server version to Claude.
• Makes outbound HTTPS requests to app.ourskylight.com to call the Skylight API on your behalf.

What this server does not do:

• Does not read, write, or scan files outside its own install directory.
• Does not execute shell commands or spawn subprocesses.
• Does not inspect other applications, processes, or network traffic.
• Does not phone home to any server other than app.ourskylight.com.

Where your credentials go:

• When installed via .mcpb, Claude Desktop stores your Skylight email/password/frame ID in its secure secret store (macOS Keychain on Mac, credential vault on Windows) — not in a plaintext config file.
• When installed manually via npm or source, credentials come from environment variables or a local .env file you control.
• Credentials are only transmitted over HTTPS to Skylight's own authentication endpoints.
• No telemetry, analytics, or third-party services.

Verifying the bundle you installed:

• All releases are published to npm with OIDC-signed provenance, cryptographically linking each package to the GitHub Actions workflow run that built it.
• Source code is fully open at github.com/rjhalvorson/skylight-mcp; the server is under 3k lines of TypeScript and auditable.
• Skylight's own privacy policy (how they handle the data you retrieve via this server) is at skylightframe.com/privacy.

Issues & Support

• Bug reports: Open an issue with steps to reproduce
• Feature requests: Open an issue describing the use case
• Questions: Start a discussion or open an issue

Please include relevant details like your Node.js version, error messages, and configuration (with sensitive values redacted).

License

MIT

Disclaimer

This is an unofficial integration. The Skylight API is reverse-engineered and may change without notice. Use at your own risk.