effect-house-mcp
Connects MCP clients to TikTok Effect House to build and edit effects conversationally. Exposes the Effect House eh kernel for running JavaScript cells against the open editor, inspecting project/scene status, launching Effect House, reading kernel workspace references, searching official Effect House docs, and optionally calling automation tools such as scene inspection, DSL edits, preview captures, and image generation.
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., "@effect-house-mcp open a new project and build a freckles face effect, then preview it"
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.
effect-house-mcp
English · Português
An unofficial MCP (Model Context Protocol) server that connects Claude Code, Codex and any other MCP client to TikTok Effect House, so you can build and edit effects by conversation from your own AI sessions.
Not affiliated with or endorsed by TikTok. It relies on internal, undocumented interfaces of Effect House 5.16 that may change with any app update. Effect House and TikTok are trademarks of their respective owners.
Why it exists
Since version 5.16, Effect House includes an AI assistant (the Effect House AI panel) that launches Claude Code, Codex or Cursor inside the app. Under the hood it relies on two local components, which this project reuses:
The
ehkernel (Contents/MacOS/eh_front): a stdio MCP server whoseruntool executes JavaScript cells with anehAPI already connected to the editor (scene, APJS scripts, assets, preview, screenshots, planning). It finds the editor on its own before every cell, so it survives app restarts.The automation server (HTTP on
127.0.0.1, port announced in~/Library/Application Support/EffectHouse/Instances/*/MCP/mcp_port.json): 33 high-level tools (get_scene,edit_by_dsl,capture_preview,generate_image…).
The official docs only cover the in-app panel, which runs one agent at a time inside Effect House. This bridge lets you use the same capabilities from outside: from your own sessions, with your skills, memory and other MCP servers (Blender, image generation and so on).
Related MCP server: PlayCanvas Editor MCP Server
What the bridge adds
Tool | What it does |
| The official |
| App install and version, running editors (port, heartbeat, health), the open project, kernel state and workspace folder. |
| Opens Effect House (optionally with a project) and waits until it answers. Never starts a second editor. |
| Search and read the official docs at effecthouse.tiktok.com/learn (every page in the sitemap), converted to Markdown and cached. |
| Reads the kernel references (skills, APJS declarations, planning flows) for clients that cannot read local files. |
Automation tools | Optional ( |
The bridge also:
reads the official workspace guide (
AGENTS.md) of the installed version and serves it as the MCP serverinstructions;keeps its own copy of the kernel workspace in
~/Library/Application Support/effect-house-mcp/workspace, without the app's agent-host config files, and refreshes it when Effect House is updated;restarts the kernel if it exits and says that
sessionvalues were lost;refuses
runwith a clear message when Effect House is not open.
Requirements
macOS (tested on Apple Silicon). Other systems need the environment variables below and are untested.
Effect House 5.16 or later, installed and signed in.
Node.js 20 or later.
Install
git clone https://github.com/jepharaujo/effect-house-mcp.git
cd effect-house-mcp
npm ci
npm run build
npm run doctordoctor prints what the bridge found: the app, its version, running instances and the workspace. It exits with code 1
when something essential is missing.
Claude Code
Run this from the project folder (the absolute paths of Node and the server are stored in the registration):
claude mcp add effect-house -s user -- "$(which node)" "$(pwd)/dist/src/index.js"A cell may take up to 10 minutes (building a scene, a script and a playtest in one call). If Claude Code stops long
calls earlier, raise the limit with MCP_TOOL_TIMEOUT=660000.
Codex
In ~/.codex/config.toml, with the paths of your machine (which node and the project folder):
[mcp_servers.effect-house]
command = "/opt/homebrew/bin/node"
args = ["/path/to/effect-house-mcp/dist/src/index.js"]
startup_timeout_sec = 30
# A cell may run up to the kernel's 10-minute limit.
tool_timeout_sec = 660Other clients
Any stdio MCP client: command node, argument dist/src/index.js. Desktop apps usually need the absolute path of Node.
Usage
With Effect House open, ask your agent something like “open a new project and make a freckles face effect”. The agent
follows the official guide: it checks the project with eh.project.status(), fills and validates a plan
(eh.plan.fromTemplate / eh.plan.validate), builds the scene and verifies it with preview captures.
A cell for run:
const status = await eh.project.status();
const scene = await eh.scene.getScene();
return { status, scene };help() inside a cell lists the whole API (help('scene'), help('EHObject'), help('preview.screenshot')).
Things to keep in mind
The agent edits the open project, live, with no sandbox. Save before large changes.
Use one agent at a time: do not run the Effect House AI panel and this bridge on the same project at once.
Preview captures go to your client's AI provider, like any image the agent reads.
Effect House requires a validated plan before building a scene; that rule comes from the official kernel and the bridge keeps it.
docs_readonly fetches pages undereffecthouse.tiktok.com/learn/; the bridge only talks to the editor on127.0.0.1.
Environment variables
Variable | Use |
| App path (default: |
| Individual paths, for non-standard installs or other systems. |
| Pins the kernel to the editor that has this project open (useful with several editors). |
| Also exposes the editor's automation tools. |
| Where the workspace copy and the docs cache live. |
|
|
Architecture
MCP client (Claude Code, Codex…)
│ stdio
▼
effect-house-mcp ──────────────► docs: effecthouse.tiktok.com/learn (sitemap + cache)
│ │
│ stdio │ HTTP (127.0.0.1, port from the instance registry)
▼ ▼
eh_front ─► eh kernel ─────────► Effect House automation server ─► open editorFile | Responsibility |
| Entry point and CLI ( |
| MCP server: lists and routes tools, the bridge's own tools. |
|
|
| Client of the editor's HTTP server; retries a call only when the connection was refused. |
| Instance registry, heartbeat and health check. |
| Workspace copy, server instructions and |
| Sitemap, search, cache and HTML → Markdown conversion of the docs. |
| Remembers the kernel tool list per version, so listing tools does not start the kernel. |
Development
npm run check # lint (Biome), types and unit tests
npm run smoke # live, read-only check with Effect House open (run npm run build first)
npm run docs:index # cache every docs page for full-text searchUnit tests do not need Effect House. smoke starts the bridge the way an MCP client would and calls each tool family.
Tested with Effect House 5.16.0 on macOS (Apple Silicon), Node.js 25 and Claude Code. Issues and pull requests are welcome, especially reports from other Effect House versions.
Troubleshooting
"Effect House is not open": open the app or call
launch; check withinstances.The kernel does not start:
npm run doctorshould showehFrontExists: true. Versions before 5.16 have no kernel.Several editors open: set
EH_PROJECTto the folder of the project the agent should use.Docs search matches only URLs: full text joins the index as pages are read, or all at once with
npm run docs:index.
License
MIT.
Available Tools
8 toolsdocs_readARead-only
Read one official Effect House documentation page as Markdown. Accepts a full URL or a path under /learn/, for example guides/api-reference/scene/transform. Long pages are paged with offset.
Inputs: url (required), offset, refresh, maxChars.
docs_searchARead-only
Search the official Effect House documentation at effecthouse.tiktok.com/learn (getting started, workspace objects and components, editor panels, Visual Scripting nodes, APJS API reference, tutorials, publishing). Matches page paths and, for pages already read or indexed, titles and text. Returns URLs to pass to docs_read.
Inputs: query (required), limit, section.
instancesARead-only
Find Effect House: the installation and version, every running editor instance (port, heartbeat, health), the project each one has open, the eh kernel state and the workspace folder. Call it first when a cell cannot reach the editor.
Inputs: includeProject.
launchAIdempotent
Open Effect House and wait until its automation server answers. With project (a project folder or its .ehproj file) the editor opens that project. When Effect House is already running nothing is launched; open projects from a run cell with eh.project.open(path) instead (see help('project')).
Inputs: project, waitSeconds.
resetB
Discard eh kernel state (session values and connection).
Inputs: no named parameters.
runA
Run a JavaScript cell in the Effect House eh kernel, which drives the open editor through a pre-connected eh API. The kernel is not available right now; call instances to see why.
(Bridge note: Effect House must be open. instances shows the editor the next cell uses; launch opens it.)
Inputs: code, name, path, timeoutMs.
statusB
Report eh kernel status: cells run, instance, project and connection.
Inputs: no named parameters.
workspace_readARead-only
Read a file or list a folder of the eh kernel workspace: AGENTS.md, flow/, skills/, APJS/ declarations, reference/, Planning/. Paths are relative to the workspace root, or absolute inside it. Use it when your client cannot read local files.
Inputs: path, offset, maxChars.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools are clearly distinct: docs_search/docs_read, workspace_read, launch, run, and reset each target a different action. The main overlap is between `instances` and `status`, which both report instance, project, connection, and kernel state, so an agent may hesitate between them. Descriptions provide enough guidance to recover, but the boundary is not perfectly sharp.
The set mixes bare verbs (`reset`, `launch`, `run`), bare nouns (`instances`, `status`), and prefixed action names (`docs_search`, `docs_read`, `workspace_read`). The prefixed group is consistent, but the overall convention varies across the surface. It remains readable, just not predictable.
Eight tools is well within the ideal 3-15 range for a focused editor-bridge server. Each operation maps to a meaningful lifecycle step: discover, launch, run, inspect, reset, and documentation/workspace access. No tool feels gratuitous, though `status` is somewhat redundant with `instances`.
The surface covers the core workflow for driving Effect House: locating/launching the editor, running kernel cells, checking status, resetting state, reading docs, and reading workspace files. Minor gaps exist around writing workspace files or managing projects directly, but most agents can work around those via `run` cells.
Related MCP Connectors
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate Douyin Xiangsu AR effects through MCP, including scene editing, asset binding, TypeScript scripting, compilation, preview screenshots, and interactive playtesting.28MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to automate the PlayCanvas Editor through a built-in MCP client, with no browser extension needed. Provides tools for entities, scripts, assets, scenes, templates, animation, builds, store imports, viewport and editor control, plus runtime launching with screenshots, logs and input to verify that projects actually run.-
- FlicenseNot gradedqualityAmaintenanceLets AI agents drive the PlayCanvas Editor directly—creating and editing entities, scripts, assets, templates, animations, scenes, builds, and version control—and then launch the project to verify it actually runs. It also covers project management, viewport control, runtime input, logs, and screenshots, with the MCP client built into the Editor so no browser extension is needed.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to automate the PlayCanvas Editor directly through its built-in MCP client, manipulating projects, entities, scripts, assets, scenes, builds and version control, then launching the app and inspecting runtime state and screenshots to confirm scenes actually run.-