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: elgato-keylight

Requirements

• Node.js 20+

• One or more Twinkly devices on the same local network

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

Quick start

With Claude Code, one command:

claude mcp add twinkly --env TWINKLY_IP=192.168.1.50 -- npx -y twinkly-mcp

Replace the IP with your device's, or drop --env entirely and use --env TWINKLY_DISCOVERY=true to let the server find your lights on the network.

For other clients, see Connecting an MCP client below. Nothing to clone or build — npx fetches the package on first run.

To hack on the server itself, see Development.

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, Cursor, and other stdio clients

Add the server to your client's MCP configuration — claude_desktop_config.json for Claude Desktop, .mcp.json in a project for Claude Code, .cursor/mcp.json for Cursor:

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

Restart the client, and the Twinkly tools will be available to the assistant. Keep the -y — without it npx may stall on an install prompt that the client can't answer.

Any variable from Configuration can go in that env block: TWINKLY_DISCOVERY instead of a fixed IP, TWINKLY_READONLY to expose only the read tools, and so on.

Streamable HTTP

Run the server with the HTTP transport:

TWINKLY_IP=192.168.1.50 TWINKLY_TRANSPORT=http TWINKLY_PORT=3000 npx -y 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

git clone https://github.com/paztek/twinkly-mcp.git && cd twinkly-mcp
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