twinkly-mcp

A Model Context Protocol (MCP) server that gives AI agents control of your Twinkly lights.

Point an MCP-capable assistant (Claude Desktop, Claude Code, etc.) at this server and ask it to turn your lights on, set a color, change brightness, or switch effects — in plain language.

It's built on top of the @twinklyjs/twinkly library, which talks to Twinkly devices over their local network API.

What you can do

Ask your assistant things like:

• "Turn the Christmas tree lights on / off"

• "Make the lights warm white at 40% brightness"

• "Set them to green"

• "Switch to the sparkle effect"

• "What are my lights doing right now?"

• "Discover my Twinkly devices"

Related MCP server: lifx-mcp-server

Requirements

• Node.js 20+

• One or more Twinkly devices on the same local network

• An MCP client (e.g. Claude Desktop or Claude Code)

Installation

npx twinkly-mcp

(Or clone this repo and run npm install && npm run build, then node dist/index.js.)

Configuration

The server is configured via environment variables (CLI flags and an optional JSON config file are also supported — see CLAUDE.md).

Devices

Don't know your device's IP? Enable discovery, or just ask the assistant to "discover my Twinkly devices".

Transport, safety & diagnostics

Tools

Every device-targeting tool takes an optional device argument (a name from list_devices); omit it to use the default device.

Discovery & status (read-only)

Control

Admin (gated behind TWINKLY_ALLOW_ADMIN=true)

The riskier device operations the underlying library can do (firmware, WiFi/network, MQTT, mic, factory reset) are intentionally not exposed.

Connecting an MCP client

Claude Desktop / Claude Code (stdio)

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "twinkly": {
      "command": "npx",
      "args": ["twinkly-mcp"],
      "env": {
        "TWINKLY_IP": "192.168.1.50"
      }
    }
  }
}

Restart the client, and the Twinkly tools will be available to the assistant.

Streamable HTTP

Run the server with the HTTP transport:

TWINKLY_IP=192.168.1.50 TWINKLY_TRANSPORT=http TWINKLY_PORT=3000 npx twinkly-mcp

It serves the MCP endpoint at http://127.0.0.1:3000/mcp. Point an HTTP-capable MCP client at that URL.

How it works

AI assistant  ──MCP──>  twinkly-mcp  ──local HTTP/UDP──>  Twinkly device(s)

The server translates natural-language requests into MCP tool calls, which it maps onto the Twinkly device API on your local network. Your device IPs and tokens stay local — nothing is sent to the cloud by this server.

Development

npm install
npm run dev          # run in watch mode (tsx)
npm run build        # compile to dist/
npm test             # run the test suite
npm run test:coverage

# Real-device smoke test (read-only; skipped without a device):
TWINKLY_IP=192.168.1.50 npx vitest run src/integration.test.ts

See CLAUDE.md for architecture, the full configuration reference, and the build history.

License

ISC