tiktok-live-studio-mcp
Provides tools to control TikTok LIVE Studio, allowing MCP clients to manage scenes, sources, audio, microphone, recording, actions, and LIVE state.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tiktok-live-studio-mcp Check whether TikTok LIVE Studio is connected and list my scenes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TikTok LIVE Studio MCP
A local Model Context Protocol server for Windows that lets Codex, Claude Code, Claude Desktop, and other stdio MCP clients control TikTok LIVE Studio through its localhost Stream Deck Socket.IO channel.
The server does not use mouse automation, OCR, browser automation, or screen coordinates. It discovers the running LIVE Studio process and its owned port, validates the protocol, acknowledges each action, and verifies readable state changes.
Community project. Not affiliated with TikTok, ByteDance, Elgato, Anthropic, or OpenAI.
Features
Twelve typed MCP tools for status, scenes, sources, audio, microphone, recording, actions, and LIVE control.
Official MCP TypeScript SDK with stdio transport.
Windows process, installed-version, and process-owned port discovery.
Automatic rediscovery when LIVE Studio restarts on a different port.
Idempotent scene/source/audio/microphone/recording/LIVE operations.
Action-result validation plus post-action state verification.
Cross-process mutation lock for multiple locally configured MCP clients.
Structured error contract and compact JSONL evidence logs.
Mock Socket.IO, MCP contract, real safe integration, opt-in full integration, built stdio, packaging, and release gates.
Related MCP server: computer-use-windows
Requirements
Windows 10 or Windows 11.
Node.js 20 or newer.
TikTok LIVE Studio installed. Start it before running doctor or real integration checks.
Quick start
git clone https://github.com/dannguyen9x/tiktok-live-studio-mcp.git
cd tiktok-live-studio-mcp
npm.cmd ci
npm.cmd run build
npm.cmd run doctor
npm.cmd run mcp:smokeThen connect your MCP client using the client setup guide. For a complete walkthrough, safety model, examples, updates, and uninstall steps, read the full user guide or Vietnamese user guide.
Run the server directly:
npm.cmd startMCP uses stdout, so ordinary runtime logs are written to artifacts/evidence/runtime.jsonl rather than stdout.
MCP client configuration
Copy the relevant example and replace C:/path/to/tiktok-live-studio-mcp with the absolute clone path:
.mcp.json.exampleconfig/claude-desktop.example.jsonconfig/claude-code.example.jsonconfig/codex.example.toml
The common stdio configuration is:
{
"mcpServers": {
"tiktok-live-studio": {
"command": "node",
"args": [
"C:/path/to/tiktok-live-studio-mcp/dist/src/index.js"
],
"env": {
"TTLS_LOG_PATH": "C:/path/to/tiktok-live-studio-mcp/artifacts/evidence/runtime.jsonl"
}
}
}
}Restart the MCP client after changing its configuration.
For current Codex and Claude Code CLI commands, Claude Desktop configuration, generic-client setup, and verification steps, see docs/CLIENT_SETUP.md.
Example requests
Once the server is connected, ask your MCP client naturally:
Check whether TikTok LIVE Studio is connected and list my scenes.
Switch LIVE Studio to the exact scene "Gameplay".
Hide source "Starting Soon" in scene "Gameplay".
Mute the microphone in LIVE Studio.
Start a local recording, but do not start LIVE.For LIVE state changes, explicitly authorize the dedicated tool call:
Start LIVE using studio_start_live with confirm set to true.Always review account, audience, scene, audio, and recording state before authorizing a LIVE action.
Tools
Tool | Behavior |
| Read running, connected, app version, endpoint, active scene, recording state, and LIVE state. |
| List scenes and the active scene. |
| Idempotently switch to an exact scene and verify it. |
| List source names, internal IDs, and visibility for the active or named scene. |
| Set source visibility without a blind toggle; temporarily switches/restores scene when required. |
| Idempotently set and verify aggregate microphone mute. |
| Idempotently set and verify desktop/audio-output mute. |
| Start recording only when stopped and verify the state. |
| Stop recording only when active and verify the state. |
| Trigger a verified parameterless Stream Deck action and require LIVE Studio acknowledgement. |
| Require |
| Require |
The generic action enum contains live-pause, highlight, recording-gallery, co-host, treasure-box, say-hi, guess-game, play-together, goody-bag, team, game-rewards, live-goal, multi-guest, vote, promote, and viewer-wishes.
Some generic actions are conditional. LIVE Studio returns result code -1 when the verified action exists but the current account, LIVE state, eligibility, or panel state does not permit it. The MCP tool returns that as a structured ACTION_FAILED result rather than pretending the action succeeded.
Verified local protocol
Field | Value |
Endpoint |
|
Socket.IO path |
|
Namespace |
|
Transport |
|
WebSocket subprotocol |
|
Join |
|
State |
|
Action |
|
Action result |
|
The contract was verified against LIVE Studio 1.33.2. See docs/PROTOCOL.md for payloads, status values, action IDs, and evidence provenance.
Reliability and safety model
Every mutation acquires
%TEMP%\tiktok-live-studio-mcp.mutation.lock, reads current state, emits at most one action, verifies readable state, and releases the lock.A crashed lock owner is detected by PID and recovered.
Source operations restore the original scene in
finally.Toggle-like mutations are never automatically retried after an uncertain result.
LIVE start/end requires literal
confirm:true.Disconnects trigger process and port rediscovery rather than retrying forever against a stale endpoint.
Malformed settings or action responses produce
PROTOCOL_MISMATCH.
Every tool error contains:
code, message, operation, appVersion, endpoint, socketEvent,
attempt, suggestedFix, evidencePathTests
CI-safe checks:
npm.cmd run test:ciSafe real integration with LIVE Studio open:
npm.cmd run doctor
npm.cmd run test:integration
npm.cmd run mcp:smoke
npm.cmd run smokeThe safe real suite switches/restores a scene, changes/restores source visibility, and changes/restores microphone mute. It never starts LIVE.
For a deliberately opt-in real audio, recording, LIVE, and generic-action gate, read docs/FULL_INTEGRATION.md. It requires explicit environment confirmations and writes a restoration report.
Full local release evidence:
npm.cmd run verify:finalSee docs/VERIFICATION.md for what each gate proves.
Protocol research
npm.cmd run protocol:researchThis executes npm view ttls-controller --json, downloads the published package with npm pack ttls-controller, records official Elgato Marketplace metadata, and hashes protocol-bearing files from the installed LIVE Studio version. Generated machine-specific evidence is excluded from Git; see artifacts/README.md.
Project layout
src/mcp/ MCP server and schemas
src/domain/ state policy, errors, mutation lock
src/adapters/ttls/ Socket.IO protocol adapter
src/discovery/ Windows process/version/port discovery
src/logging/ structured JSONL logging
tests/unit/ mock Socket.IO and domain tests
tests/contract/ MCP and protocol contract tests
tests/integration/ safe real LIVE Studio integration
scripts/ doctor, smoke, research, full and release gates
docs/ protocol, architecture, and verification guidesContributing and security
Read CONTRIBUTING.md before submitting a change. Report vulnerabilities through GitHub private vulnerability reporting as described in SECURITY.md. Do not publish raw evidence logs, credentials, recordings, account data, or proprietary LIVE Studio bundles.
Documentation
License
MIT. See LICENSE.
Available Tools
12 toolsstudio_get_statusGet TikTok LIVE Studio statusA
Read process, Socket.IO connection, scene, recording, and LIVE state without changing Studio.
Inputs: no named parameters.
studio_list_scenesList LIVE Studio scenesA
List scenes and the active scene from verified sync_settings state.
Inputs: no named parameters.
studio_list_sourcesList scene sourcesA
List source names, IDs, and visibility for the active or named scene.
Inputs: sceneName.
studio_set_audio_muteSet audio output muteA
Idempotently set and verify the LIVE Studio audio output mute state.
Inputs: muted (required).
studio_set_microphone_muteSet microphone muteA
Idempotently set and verify the aggregate LIVE Studio microphone mute state.
Inputs: muted (required).
studio_set_source_visibilitySet source visibilityA
Set, verify, and preserve source visibility without a blind toggle. Restores the original scene when targeting another scene.
Inputs: visible (required), sourceName (required), sceneName.
studio_start_liveStart LIVEB
Start LIVE only with confirm:true and only when readable state makes the toggle safe.
Inputs: confirm (required).
studio_start_recordingStart recordingA
Start local recording only when stopped, then verify recording state.
Inputs: no named parameters.
studio_stop_liveStop LIVEA
Stop LIVE only with confirm:true and verify the resulting offline state.
Inputs: confirm (required).
studio_stop_recordingStop recordingA
Stop local recording only when active, then verify recording state.
Inputs: no named parameters.
studio_switch_sceneSwitch LIVE Studio sceneA
Idempotently switch to an exact scene and verify the resulting active scene.
Inputs: sceneName (required).
studio_trigger_actionTrigger a verified Stream Deck actionA
Emit one action from the verified LIVE Studio 1.33.2 Stream Deck protocol. Parameterized and stateful actions should use dedicated tools.
Inputs: action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: status, scenes, sources, audio (mic vs output), recording, live, and a generic trigger. The overlap between microphone_mute and audio_mute is clearly separated by description.
All tool names follow the consistent pattern studio_<verb>_<object>, using snake_case throughout. Verbs like get, list, switch, set, start, stop are used predictably.
12 tools is well within the ideal 3-15 range and covers the full scope of controlling a live studio without unnecessary bloat.
Core lifecycle is covered: read status, manage scenes/sources, control audio, recording, and live state. Minor gaps like scene creation or source editing exist, but the generic trigger_action and robust state verification reduce dead ends.
Maintenance
Related MCP Connectors
Hosted TikTok Pages MCP server, with each action switched on or off per account.
The official MCP Server for the Mux API
MCP server for Hailuo (MiniMax) AI video generation
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseBqualityDmaintenanceA server that provides tools to control OBS Studio remotely via the OBS WebSocket protocol, enabling management of scenes, sources, streaming, and recording through an MCP client interface.100167GPL 2.0
- AlicenseNot gradedqualityDmaintenanceA standalone MCP server for Windows desktop control, enabling screenshots, mouse and keyboard input, app launch, window/display management, and clipboard access via natural language.3MIT
- AlicenseBqualityDmaintenanceMCP server enabling LLMs to control OBS Studio through high-level show and effect APIs.18MIT
- AlicenseBqualityDmaintenanceMCP server for controlling OBS Studio via obs-websocket, enabling scene switching, source management, streaming, recording, and text overlays through natural language.36152 PyPI5MIT