Skip to main content
Glama
Sign In
@lumiastream/mcp

@lumiastream/mcp

Official
by lumiastream
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@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)

Related MCP server: companion-mcp-server

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.

Stream management

  • set_stream_info — change the stream title and/or category (Twitch, Kick).

  • create_clip — create a Twitch clip; its id/url land in the twitch_last_clip_* variables.

  • create_stream_marker — mark the current moment of the Twitch broadcast.

  • send_announcement — highlighted Twitch chat announcement.

  • run_commercial — run a Twitch ad break (30–180 seconds).

  • set_chat_mode — toggle Twitch slow / subscriber-only / follower-only / emote-only chat.

  • create_poll / end_poll — start a Twitch poll; end it (archive, or terminate leaving it visible).

  • create_prediction / end_prediction — start a Twitch prediction; resolve it with the winning outcome, or cancel and refund.

  • clear_chat — clear Twitch chat for everyone.

  • pin_message — pin or unpin a Twitch chat message.

  • manage_moderator — grant or revoke Twitch moderator.

  • control_song_request — add/skip/play/pause/remove/clear song requests.

  • get_loyalty_points — read a viewer's loyalty points balance.

  • set_counter — set a counter variable to an exact value.

  • manage_chatbot_command — create/update/delete a chatbot command (unlimited on every plan).

Overlays, session & economy

  • control_overlay — show/hide overlays and layers, move and resize 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"
			}
		}
	}
}

Step-by-step instructions for each client (Claude Desktop, Claude Code, Cursor, Codex, VS Code, Windsurf, Gemini CLI) are in the setup guide.

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.

Available Tools

41 tools
clear_chatClear chatA
Destructive

Clear the entire Twitch chat for all viewers. This cannot be undone.

Inputs: no named parameters.

control_fuzeControl FuzeA

Start, stop, or toggle Fuze, or set its audio sensitivity (a value below 100 makes it less sensitive).

Inputs: action (required), sensitivity.

control_overlayControl an overlayA

Show or hide an overlay or a layer, move or resize a layer, or set a layer's content. "target" is the overlay name/uuid for the "visibility" action, or the layer id for the layer actions (both are found in Lumia's overlay settings).

Inputs: action (required), target (required), x, y, +4 more.

control_queueControl the alert queueB
Destructive

Pause, resume, or clear Lumia's alert/effect queue, or clear all command cooldowns.

Inputs: action (required).

control_song_requestControl song requestsA

Control the song request queue (plays through Spotify). "add" queues a song by search query or link; "skip" jumps to the next song; "play"/"pause" control playback; "remove" drops a request (the last one, or a specific id); "clear" empties the whole queue.

Inputs: action (required), query, platform, username, +1 more.

create_clipCreate a clipA

Create a Twitch clip of the last moments of the live stream. The clip id and url land in the "twitch_last_clip_id" and "twitch_last_clip_url" variables — read them with get_variable afterwards. Only works while live on Twitch.

Inputs: no named parameters.

create_pollCreate a pollA

Start a Twitch poll. The poll id lands in the "twitch_current_poll_id" variable, and end_poll targets the last poll created this way. Only works while live on Twitch.

Inputs: title (required), choices (required), duration.

create_predictionCreate a predictionA

Start a Twitch channel-points prediction. The prediction id and outcomes are cached so end_prediction can resolve it by outcome title. Only works while live on Twitch.

Inputs: title (required), outcomes (required), duration.

create_stream_markerCreate a stream markerA

Mark the current moment of the Twitch broadcast (shows up in the Highlighter for editing later). Only works while live on Twitch.

Inputs: description.

delete_messageDelete a chat messageC
Destructive

Delete a specific chat message by its message id.

Inputs: message_id (required), platform.

end_pollEnd the current pollA

End the Twitch poll that is currently running. Only finds polls that were created through Lumia.

Inputs: status.

end_predictionEnd the current predictionA

Resolve or cancel the Twitch prediction that is currently running. To resolve, name the winning outcome — it must match one of the prediction's outcome titles (case-insensitive). Canceling refunds all channel points. Only works for predictions created through Lumia in the current app session.

Inputs: status, winning_outcome.

get_loyalty_pointsGet loyalty pointsA
Read-only

Read a viewer's current loyalty points balance. To change it, use loyalty_points.

Inputs: username (required), platform.

get_recent_eventsGet recent stream eventsA
Read-only

Return live events (chat, chat commands, follows, subs, bits, raids, donations, heart-rate, etc.) that Lumia has pushed since this server started. Optionally filter by a type substring (e.g. "follow", "chat", "sub", "bits") or origin (e.g. "twitch"). If nothing is buffered yet, check the returned status.connected.

Inputs: type, limit, origin.

get_settingsGet Lumia settingsA
Read-only

Discover what this Lumia Stream user actually has set up. The default summary returns states, counts, and studio scene/theme/animation names; large lists are counts only. Pass a section to fetch a full list: "commands" (all chat/chatbot/points/extension command names), "alerts", "lights", or "voices". Call this before triggering things by name, since every user's setup differs.

Inputs: section.

get_stateGet stream stateA
Read-only

Get a snapshot of the current stream: streamer name, live status, now-playing song, and heart rate, plus a per-platform breakdown (followers, subscribers, viewers, latest follower/subscriber, live) for every connected platform, alongside cross-platform "totals". Platforms with no data are omitted. Note: Lumia "stream mode" on/off isn't a variable, so per-platform "live" is the closest live indicator.

Inputs: no named parameters.

get_variableGet a variableA
Read-only

Read the current value of a Lumia variable, e.g. "twitch_username" or a custom variable you created.

Inputs: name (required).

get_variablesGet multiple variablesA
Read-only

Read several Lumia variables at once by name. Returns a map of name to value. Use get_settings first if you're unsure which variables exist.

Inputs: names (required).

loyalty_pointsAdd/remove loyalty pointsA

Add or remove a viewer's loyalty points. Use a negative amount to remove points.

Inputs: amount (required), username (required), platform.

manage_chatbot_commandCreate/update/delete a chatbot commandA
Destructive

Create, update, or delete a chatbot command (chatbot commands are unlimited on every plan). Names are slugified (lowercase, spaces become dashes). "message" is the chat reply and is required for create; it supports {{variables}}. Update merges only the fields you pass; delete refuses built-in system commands. Requires an up-to-date Lumia Stream.

Inputs: name (required), action (required), aliases, enabled, +5 more.

manage_moderatorAdd/remove a moderatorA
Destructive

Grant or revoke a user's moderator role on Twitch.

Inputs: action (required), username (required).

moderate_userModerate a userA
Destructive

Ban, unban, or time out a user, or grant/remove VIP. Ban/unban/timeout work on Twitch and YouTube; VIP is Twitch only. For "timeout", set duration_minutes and optionally a reason.

Inputs: action (required), username (required), reason, platform, +1 more.

pin_messagePin/unpin a chat messageA

Pin a Twitch chat message by its message id, or unpin. For "unpin", omit message_id to unpin whatever is currently pinned.

Inputs: action (required), message_id.

run_commercialRun a commercialA

Run an ad break on the Twitch channel. Twitch serves an ad as close to the requested length as possible. Only works while live on Twitch, and respects the channel's ad cooldown.

Inputs: duration.

send_announcementSend a chat announcementB

Post a highlighted announcement message to Twitch chat.

Inputs: message (required).

send_chat_messageSend a chat messageA

Post a message to your live chat through Lumia's chat bot. The platform must be connected and the chat bot enabled. Set as_streamer to post as yourself instead of the bot account.

Inputs: message (required), platform, as_streamer.

set_chat_modeSet a chat modeA

Turn a Twitch chat mode on or off: slow mode, subscriber-only, follower-only, or emote-only.

Inputs: mode (required), enabled (required), duration.

set_colorSet light colorA

Set the color and brightness of the user's lights. Provide exactly one of: hex (e.g. "#FF4076"), rgb ({ r, g, b } each 0-255), or ct (color temperature 2900-7000 kelvin). Brightness is 0-100; transition and duration are in milliseconds.

Inputs: ct, hex, rgb, hold, +3 more.

set_command_stateEnable/disable a command or folderA

Enable or disable a command, or a whole command folder, by name. For commands, "kind" picks which list the name belongs to (chat, chatbot, Twitch channel points, Kick points, or Twitch extension); points/extension kinds also sync the platform-side reward state on an up-to-date Lumia Stream.

Inputs: name (required), enabled (required), kind, target.

set_counterSet a counterA

Set a counter variable to an exact numeric value, e.g. reset a death counter to 0. Creates the counter if it doesn't exist yet.

Inputs: name (required), value (required).

set_lumia_stateStart/stop LumiaA

Turn Lumia's light control on or off, toggle it, or reset all lights to their default state.

Inputs: action (required).

set_stream_infoSet stream title/categoryA

Change the live stream title and/or category. Provide title, category, or both. Works on Twitch and Kick; the category is matched by name search on the platform. YouTube is not supported.

Inputs: title, category, platform.

set_stream_modeSet stream modeA

Turn Lumia Stream Mode on or off, or toggle it.

Inputs: mode (required).

set_studioSet studio scene/theme/animationA

Trigger a Lumia Studio scene, theme, or animation by name. Use get_settings to see valid values under options.studio-scene / studio-theme / studio-animation.

Inputs: kind (required), name (required), duration.

set_variableSet a variableA

Create or update a custom Lumia variable that overlays, commands, and custom code can read.

Inputs: name (required), value (required).

shoutoutShout out a userA

Shout out a user: finds a clip of them if possible, shows it on your overlays, and posts a shoutout in chat.

Inputs: username (required), platform.

speakText to speechA

Speak text aloud through Lumia's TTS engine on the streamer's machine. Optionally pick a voice from get_settings (options.tts.voices). Volume is Windows-only, 0-100.

Inputs: text (required), voice, volume.

translate_messageTranslate a message to chatA

Translate a message into a target language and post it to chat. "language" is a code like "en", "es", or "fr".

Inputs: message (required), language (required), platform, username.

trigger_alertTrigger an alertA

Simulate a platform alert such as "twitch-follower", "twitch-subscriber", "twitch-bits", "youtube-superchat", or "kofi-donation". Use get_settings (options.alert.values) to see which alerts the user has configured. extraSettings can carry variables like { "username": "lumia", "bits": 1000 }.

Inputs: name (required), extraSettings.

trigger_commandTrigger a commandA

Trigger one of the user's configured commands by name. "kind" selects which list it comes from: a chat command, a chatbot command, a Twitch channel-points reward, or a Twitch extension command. Use get_settings to see valid names.

Inputs: name (required), hold, kind, extraSettings.

wait_for_eventWait for the next eventA
Read-only

Block until the next matching live event arrives, or until the timeout. Use it to react in real time — e.g. wait for the next follower, then greet them by name. Returns the event, or a timedOut result if none arrived in time.

Inputs: type, origin, timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but there is minor overlap, e.g., control_queue (manages alert/effect queue and command cooldowns) and set_command_state (enables/disables commands) both relate to command management, potentially causing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, e.g., clear_chat, create_clip, set_color, trigger_alert. No mixing of conventions, making the set predictable and easy to navigate.

    Tool Count4/5

    With 41 tools, the server covers a broad integration with Lumia Stream's features. While slightly higher than the typical ideal range (3-15), the count is justified by the complexity of streaming control across multiple platforms.

    Completeness4/5

    The tool set covers core streaming operations: chat, events, polls, predictions, lights, overlays, commands, alerts, moderation, and variables. Minor gaps exist, such as a dedicated tool for directly managing Twitch channel points rewards, but overall coverage is strong.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • ha-mcp

      osrd-gh
      A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI assistants to control Home Assistant via natural language, including device control, automation management, and system configuration.
      MIT

    • sundial

      Itstommy10
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Sundial, enabling AI assistants to control Corsair iCUE lighting, manage presets, and configure automation based on sunrise/sunset.
      MIT
    • wlanpi-mcp

      wlanpi-mcpofficial

      WLAN-Pi
      A
      license
      B
      quality
      B
      maintenance
      An MCP server that exposes WLAN Pi capabilities like device info, Wi-Fi scanning, service management, and VLANs to AI assistants via the wlanpi-core REST API.
      71
      6
      BSD 3-Clause