Family Kiosk Display

A polished, animated kiosk display that can be controlled by an LLM through MCP tool calls.

What this provides

• MCP server over stdio with kiosk control tools
• HTTP kiosk display endpoint at http://localhost:8787
• Real-time updates via WebSocket (/ws)
• Large readable typography and smooth animated transitions
• Support for mixed scene elements: text, images, and videos
• Overlay announcements for urgent family updates
• Auto-advancing playlist mode for unattended display rotation

MCP integrations

The server supports two MCP transports:

1. Stdio (default) — for LLM clients that use stdio-based MCP
2. HTTP streaming — for tools like n8n, Zapier, or custom integrations

Stdio transport

Standard MCP over stdin/stdout. Used by most LLM clients as a subprocess.

HTTP streaming transport

call MCP tools from n8n or any HTTP client.

• GET /mcp/tools — list all available tools
• POST /mcp/call — invoke a tool (JSON response)
• POST /mcp/stream — invoke a tool (Server-Sent Events response)

Example: n8n HTTP POST to /mcp/call

{
  "tool": "kiosk_show_chores",
  "arguments": {
    "dueToday": ["Dishes", "Homework", "Vacuum living room"],
    "done": ["Breakfast prep", "Make beds"],
    "points": ["Jane: 12 pts", "Max: 8 pts"],
    "theme": "party"
  }
}

Response:

{
  "ok": true,
  "message": "Chore dashboard rendered",
  "state": { /* full kiosk state */ }
}

Run locally

1. Install dependencies
2. Start the server
3. Open kiosk display in browser

The server process hosts both:

• MCP tool interface (stdio)
• Display web server (http://localhost:8787)

Example scene payload for kiosk_set_playlist

Use this shape from your LLM client:

• title, subtitle
• theme: aurora | sunrise | ocean | midnight | party
• transition: slide | fade | zoom
• autoAdvance, autoAdvanceSec
• scenes[]
  • title, subtitle, accent, durationSec
  • elements[]
    • type: text with heading, body
    • type: image with url, optional caption
    • type: video with url, optional caption, and booleans muted, autoplay, loop

High-level family workflow tools

For most home-assistant use cases, prefer these tools over raw playlist JSON:

• kiosk_show_calendar
  • Inputs: dayLabel, events[], now, next, highlight
  • events[] accepts either simple strings or objects with when, time, label
• kiosk_show_chores
  • Inputs: dueToday[], done[], points[]
• kiosk_show_meal_plan
  • Inputs: breakfast, lunch, dinner, prep[], shopping[]
• kiosk_show_school_run
  • Inputs: leaveBy, weather, checklist[], reminders[]
• kiosk_announce
  • Inputs: message (required), details[], emoji, showOverlay

Each of the tools above also supports optional visual controls:

• title, subtitle
• theme: aurora | sunrise | ocean | midnight | party
• transition: slide | fade | zoom
• autoAdvance, autoAdvanceSec

MCP client wiring

Use mcp.client.example.json as a reference for your MCP host configuration.

Customization ideas

• Pipe in family calendar data from Home Assistant
• Add weather and transit cards as text elements
• Display chore boards and rotating reminders
• Build holiday themes by switching theme and scene media

Notes

• Keep media URLs publicly accessible by the kiosk browser.
• For local/private media, serve files from public/ and reference relative paths.