MCP Server

The Estella editor includes a built-in MCP (Model Context Protocol) bridge that allows AI assistants like Claude to read and modify your scene in real-time. The MCP server acts as a thin wrapper that translates MCP tool calls into HTTP requests to the running editor.

Prerequisites

Estella editor v0.11.0 or later
Node.js 18+
An MCP-compatible AI client (e.g., Claude Desktop, Claude Code, Cursor)

Installation

Configure your AI client to use the MCP server. No separate install step is needed — npx fetches it directly from GitHub.

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "estella-editor": {
      "command": "npx",
      "args": ["-y", "github:esengine/estella-mcp-server"]
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "estella-editor": {
      "command": "npx",
      "args": ["-y", "github:esengine/estella-mcp-server"]
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "estella-editor": {
      "command": "npx",
      "args": ["-y", "github:esengine/estella-mcp-server"]
    }
  }
}

3. Start the editor

Open your project in the Estella editor. The MCP bridge automatically registers itself at ~/.esengine/bridge-<port>.json, which the MCP server discovers on startup.

How It Works

AI Client ←→ MCP Server (stdio) ←→ HTTP Bridge ←→ Estella Editor

The editor starts an HTTP bridge server on a random available port
It writes a discovery file to ~/.esengine/bridge-<port>.json
The MCP server reads the discovery file to find the running editor
AI tool calls are translated to HTTP GET/POST requests

Available Tools

Scene Inspection

Tool	Description
`get_hierarchy`	List all entities in the scene tree
`get_entity`	Get entity data (all components and properties)
`get_component`	Get a specific component’s properties
`get_children`	List child entities
`list_assets`	List project assets by type
`read_asset`	Read an asset file’s content

Entity Operations

Tool	Description
`create_entity`	Create a new entity (optionally under a parent)
`delete_entity`	Delete an entity
`rename_entity`	Rename an entity
`reparent_entity`	Move an entity to a new parent
`add_component`	Add a component to an entity
`remove_component`	Remove a component from an entity

Property Editing

Tool	Description
`set_property`	Set a component property value (with undo support)
`get_selection`	Get the currently selected entity
`select_entity`	Select an entity in the editor

Timeline

Tool	Description
`get_timeline`	Read timeline data for an entity
`update_timeline`	Modify timeline tracks, keyframes, or properties
`write_asset`	Write modified asset data back to disk

Play Mode

Tool	Description
`play`	Enter play mode
`stop`	Exit play mode
`pause`	Pause/resume play mode
`set_play_speed`	Adjust playback speed

UI Creation

Create fully configured UI widget hierarchies with a single tool call. Entities are auto-parented under the Canvas.

Tool	Description
`create_text`	Create a text label with content, fontSize, color, and alignment
`create_image`	Create an image element with tint color and size
`create_panel`	Create a panel with background and mask
`create_button`	Create a button with background and interactable
`create_input_field`	Create a text input field with placeholder and initial value
`create_toggle`	Create a toggle/checkbox
`create_slider`	Create a slider with fill bar and handle
`create_progress_bar`	Create a progress bar with fill
`create_scroll_view`	Create a scrollable container
`create_dropdown`	Create a dropdown/select with options

Editor State

Tool	Description
`get_console_logs`	Get recent console logs, optionally filtered by level
`get_panel_layout`	Get editor panel positions
`get_project_settings`	Get project settings
`get_build_status`	Get recent build history
`get_render_stats`	Get frame timing and performance data
`get_asset_info`	Get detailed info about an asset by UUID or path

Visual

Tool	Description
`capture_editor`	Capture a screenshot of the editor (whole window or specific panel)
`capture_diff`	Compare two screenshots pixel-by-pixel

Example Prompts

Once configured, you can ask your AI assistant things like:

“Show me all the entities in the scene”
“Change the player’s position to (100, 200)”
“Add a Sprite component to the Background entity”
“Set the idle animation speed to 0.5x”
“Take a screenshot and tell me what’s on screen”

Troubleshooting

MCP server says “No running ESEngine editor found”

Make sure the Estella editor is running with a project open
Check that ~/.esengine/ contains a bridge-*.json file
If the file exists but the editor was closed, delete stale bridge files

Connection refused errors

The bridge server binds to 127.0.0.1. If using a proxy, ensure localhost traffic is not proxied:

curl --noproxy '*' http://127.0.0.1:<port>/health

Tools return errors

Ensure the editor has a scene loaded
Entity IDs are numeric — use get_hierarchy first to find valid IDs
Component names are case-sensitive (e.g., Transform, Sprite, SpineAnimation)