DesignJS MCP Tools Overview

Reference for the 20+ DesignJS MCP tools across inspect, component mutation, artboards, variables, and selection — that let AI agents inspect and edit your live HTML/CSS canvas over stdio.

DesignJS exposes a bidirectional Model Context Protocol (MCP) server that AI coding agents — Claude Code, Cursor, Codex, and any MCP-compatible client — connect to over stdio using JSON-RPC 2.0. Each tool call travels from your agent through the MCP server, across a local WebSocket bridge on 127.0.0.1:29170, and into the live GrapesJS canvas running in your browser. Responses follow the same path in reverse, arriving as JSON wrapped in MCP text content blocks.

How agents call tools

Every tool call is a standard MCP tools/call request. The arguments object maps directly to the tool’s input schema. Results are returned as a single text content block containing a JSON string — parse it to get the typed response object.

tool call example

{
  "method": "tools/call",
  "params": {
    "name": "get_html",
    "arguments": {
      "componentId": "comp-abc123"
    }
  }
}

tool result

{
  "content": [
    {
      "type": "text",
      "text": "{\"html\": \"<div class=\\\"p-4 text-gray-900\\\">Hello</div>\"}"
    }
  ]
}

All tool results are JSON-encoded strings inside the text content block. Your agent must parse the text field to access the structured response.

Transport

DesignJS uses the stdio transport defined by the MCP specification. The MCP server process (@designjs/mcp-server) is launched by your IDE or agent runner as a child process. Communication happens over the process’s stdin and stdout streams — no HTTP port is exposed by the MCP server itself (the WebSocket bridge on port 29170 is internal).

All 20+ tools

Tool	Category	Description
ping	Read	Health check — confirms the canvas is connected and returns a server timestamp
get_tree	Read	Returns the full component tree as recursive JSON, optionally limited by depth or artboard
get_html	Read	Exports clean HTML for the entire canvas or a specific component subtree
get_css	Read	Exports the CSS stylesheet for the entire canvas or a scoped component
get_screenshot	Read	Captures the canvas as a base64-encoded PNG or JPEG data URL
get_selection	Read	Returns the component IDs of whatever is currently selected in the editor
get_jsx	Read	Converts canvas HTML to a JSX string using Tailwind class names or inline styles
get_variables	Read	Reads all CSS custom properties (--var: value) from the canvas :root
add_components	Write	Inserts raw HTML onto the canvas and returns the new component IDs
update_styles	Write	Sets CSS properties on an existing component by ID
delete_nodes	Write	Removes one or more components and their children from the canvas
set_variables	Write	Writes CSS custom properties to the canvas :root, persisted to .designjs.json
create_artboard	Write	Creates a new named artboard (frame) at a given position and size
list_artboards	Read	Returns all artboards with their IDs, names, positions, and dimensions
find_placement	Read	Suggests a non-overlapping canvas position for a new artboard of the given size

Tool categories

Read tools only observe the canvas state — they are safe to call at any time and produce no side effects. Use them to gather context before deciding what to change.

Write tools mutate the canvas. Changes are reflected in the editor immediately and are persisted to .designjs.json (Cmd+S or 30-second autosave). All write operations are reversible through the editor’s undo history.

Data types

Two shared types appear across multiple tools.

ComponentNode — the recursive node returned by get_tree:

Field	Type	Description
id	string	Unique component identifier
type	string	GrapesJS component type
tagName	string?	HTML tag name (e.g. "div", "button")
classes	string[]	Applied CSS class names
attributes	Record<string, string>	HTML attributes
textContent	string?	Text content of the node
children	ComponentNode[]	Nested child nodes

ArtboardData — returned by create_artboard and list_artboards:

Field	Type	Description
id	string	Unique artboard identifier
name	string	Display name
x	number	Canvas X coordinate (world space)
y	number	Canvas Y coordinate (world space)
width	number	Width in pixels
height	number	Height in pixels