Skip to main content
Glama

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 eh kernel (Contents/MacOS/eh_front): a stdio MCP server whose run tool executes JavaScript cells with an eh API 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

run, reset, status

The official eh kernel, forwarded unchanged (text, images and errors).

instances

App install and version, running editors (port, heartbeat, health), the open project, kernel state and workspace folder.

launch

Opens Effect House (optionally with a project) and waits until it answers. Never starts a second editor.

docs_search, docs_read

Search and read the official docs at effecthouse.tiktok.com/learn (every page in the sitemap), converted to Markdown and cached.

workspace_read

Reads the kernel references (skills, APJS declarations, planning flows) for clients that cannot read local files.

Automation tools

Optional (EH_MCP_AUTOMATION_TOOLS=1): the 33 HTTP tools exposed directly. Off by default: they add ~70 KB of tool definitions and the kernel already reaches them.

The bridge also:

  • reads the official workspace guide (AGENTS.md) of the installed version and serves it as the MCP server instructions;

  • 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 session values were lost;

  • refuses run with 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 doctor

doctor 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 = 660

Other 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_read only fetches pages under effecthouse.tiktok.com/learn/; the bridge only talks to the editor on 127.0.0.1.

Environment variables

Variable

Use

EH_APP_PATH

App path (default: /Applications/Effect House.app, or what the app recorded in its app.json).

EH_EXECUTABLE_DIR, EH_FRONT_PATH, EH_WORKSPACE_TEMPLATE, EH_SUPPORT_DIR

Individual paths, for non-standard installs or other systems.

EH_PROJECT

Pins the kernel to the editor that has this project open (useful with several editors).

EH_MCP_AUTOMATION_TOOLS=1

Also exposes the editor's automation tools.

EH_MCP_STATE_DIR, EH_MCP_CACHE_DIR

Where the workspace copy and the docs cache live.

EH_MCP_LOG_LEVEL

debug, info (default), warn or error; logs go to stderr.

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 editor

File

Responsibility

src/index.ts

Entry point and CLI (serve, doctor, index-docs).

src/server.ts

MCP server: lists and routes tools, the bridge's own tools.

src/kernel.ts

eh_front client: lazy start, restart, stderr kept for diagnostics.

src/automation.ts

Client of the editor's HTTP server; retries a call only when the connection was refused.

src/registry.ts

Instance registry, heartbeat and health check.

src/workspace.ts

Workspace copy, server instructions and workspace_read (never outside the folder).

src/docs.ts, src/html.ts

Sitemap, search, cache and HTML → Markdown conversion of the docs.

src/toolcache.ts

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 search

Unit 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 with instances.

  • The kernel does not start: npm run doctor should show ehFrontExists: true. Versions before 5.16 have no kernel.

  • Several editors open: set EH_PROJECT to 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 tools
docs_readA
Read-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.

instancesA
Read-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.

launchA
Idempotent

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_readA
Read-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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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`.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate Douyin Xiangsu AR effects through MCP, including scene editing, asset binding, TypeScript scripting, compilation, preview screenshots, and interactive playtesting.
      28
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Lets 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -