@lumiastream/mcp

A Model Context Protocol server for Lumia Stream. It exposes Lumia's local API as MCP tools so an AI assistant (Claude Desktop, Claude Code, Cursor, etc.) can control lights, trigger commands and alerts, run TTS, post to and moderate chat, read live stream state, and react to events in real time.

It is a thin adapter over the local Lumia API (http://localhost:39231/api) plus its event WebSocket — the app does all the real work.

Prerequisites

• Node.js ≥ 20
• Lumia Stream running on the same machine
• The REST API enabled in Lumia: Settings → API (toggle it on and copy the token)

Tools

Discover & state

• get_settings — commands, alerts, connected lights, studio scenes/themes/animations, TTS voices. Call this first.
• get_state — snapshot: live status, viewers, follower/subscriber counts, latest names, now-playing song, heart rate.
• get_variable / get_variables / set_variable — read one or many Lumia variables, or write one.

Lights & studio

• set_color — hex, RGB, or color temperature, with brightness/transition/duration.
• set_studio — trigger a studio scene, theme, or animation.
• set_lumia_state — start/stop/toggle Lumia, or reset lights to default.

Trigger commands & alerts

• trigger_command — chat / chatbot / Twitch-points / Twitch-extension command by name.
• trigger_alert — simulate a platform alert (e.g. twitch-follower, kofi-donation).

Chat, voice & moderation

• send_chat_message — post to chat as the bot or as yourself.
• speak — text-to-speech through Lumia's engine.
• shoutout — clip + chat shoutout for a user.
• moderate_user — ban / unban / timeout / VIP.
• delete_message — remove a message by id.
• translate_message — translate and post to chat.

Overlays, session & economy

• control_overlay — show/hide overlays and layers, move layers, set content.
• set_stream_mode — stream mode on/off/toggle.
• control_queue — pause/resume/clear the queue, clear cooldowns.
• set_command_state — enable/disable a command or folder.
• control_fuze — start/stop/toggle Fuze, set audio sensitivity.
• loyalty_points — add or remove a viewer's loyalty points.

Real-time

• get_recent_events — recent live events (chat, follows, subs, bits, raids, donations) since the server started.
• wait_for_event — block until the next matching event (e.g. the next follower), then react.

Also a lumia://settings resource mirroring get_settings, and prompts (slash-commands in most clients): start_stream, brb, hype, wind_down, thank_new_followers.

Configuration

Environment variables:

Var	Default	Notes
LUMIA_TOKEN	—	Required. From Settings → API.
LUMIA_HOST	127.0.0.1
LUMIA_PORT	39231
LUMIA_SECURE	false	Set true to use the HTTPS port.

Use with an MCP client

Once published, point your client at it via npx:

{
	"mcpServers": {
		"lumia-stream": {
			"command": "npx",
			"args": ["-y", "@lumiastream/mcp"],
			"env": {
				"LUMIA_TOKEN": "your_token_here"
			}
		}
	}
}

Local development

npm install
npm run build

Then point the client at the built entry:

{
	"mcpServers": {
		"lumia-stream": {
			"command": "node",
			"args": ["/absolute/path/to/Lumia-MCP/dist/index.js"],
			"env": {
				"LUMIA_TOKEN": "your_token_here"
			}
		}
	}
}

Verify

npm run smoke builds nothing but connects to dist/index.js over stdio, lists the tools/resources, and calls get_settings. With a real token it returns live settings; without one it exercises the auth/error path:

npm run build
LUMIA_TOKEN=your_token_here npm run smoke

Adding a tool

Each type in the Lumia Send API maps to a tool. To add one:

1. Create src/tools/<name>.ts exporting register<Name>(server, client) — copy an existing file.
2. Define the inputSchema (zod) and map inputs to client.send('<type>', params).
3. Register it in src/tools/index.ts.

Remember the Lumia param convention: params.value is the target/name and params.message is the content/payload.