Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
If you are inside the Webstudio monorepo, use the local CLI exactly as node packages/cli/local.js ... as your first command path. Do not use packages/cli/bin.js for local source-tree work; it is the packaged build entry and may use stale built output.
Plain webstudio mcp starts the stdio MCP server for real MCP clients. Do not manually type or pipe raw JSON-RPC frames into it from an interactive shell or PTY. From a shell, use shortcut calls such as webstudio meta.index and webstudio insert-fragment '<json>' --dry-run for one bounded tool call. The explicit equivalent is webstudio mcp single-op-call <tool> '<json>'. Use webstudio mcp run '[{"tool":"components.find","input":{"brief":"button"}}]' for small multi-call batches in one shared CLI session. For large batches, pass a normal JSON file path such as .temp/mcp-calls.json. Do not use shell process substitution like <(...); use inline JSON or a real file.
Put each local CLI call in its own shell command; do not chain helper commands with &&, ;, command substitution, or shell wrappers around the CLI when reporting a CLI step. Do not use pnpm exec webstudio, pnpm --filter webstudio exec webstudio, or a global webstudio; those can resolve an older binary. For example:
node packages/cli/local.js mcp single-op-call meta.index
node packages/cli/local.js mcp single-op-call meta.get-more-tools '{"tools":["insert-fragment"]}'
node packages/cli/local.js mcp single-op-call insert-fragment --input-file .temp/insert-fragment.json --dry-run
Save the input as .temp/insert-fragment.json; use single quotes for JSX attributes so the JSON needs no backslash escaping:
{
"parentInstanceId": "parent-id",
"fragment": "<section ws:style={css`padding: 32px; display: grid; gap: 12px;`}><h2>Launch Kit</h2><p>A focused section created with Webstudio JSX.</p><button>Get started</button></section>"
}
The shorter local shortcut form is preferred for simple shell steps:
node packages/cli/local.js meta.index
node packages/cli/local.js meta.get-more-tools '{"tools":["insert-fragment"]}'
node packages/cli/local.js insert-fragment --input-file .temp/insert-fragment.json --dry-run
For simple authored/styled sections, run the three commands above. Do not grep source files, dump full MCP resources, or write parser scripts first. Use list-pages, get-page-by-path, or list-instances only when you still need the target parentInstanceId.
When building for a Content-mode editor, use a Content Block (ws:block) around every region that editor must change. Content-mode text and supported props are editable only in Content Block descendants; content outside is read-only. Keep reusable insertable source options in exactly one direct ws:block-template child. A missing or second template container makes the block invalid. Templates themselves are protected; an editor's inserted copy becomes editable Content Block body content. Verify this structure before handoff.
For an MDX-backed Content Block, use the dedicated content-source tools instead of generic prop mutations: connect, switch, inspect, edit, update frontmatter, reload, or disconnect the source. Confirm before replacing existing Body content. Prefer Markdown for standard document content; it automatically uses unique matching semantic templates. Use lowercase JSX such as <section> or <svg> for HTML or SVG that Markdown cannot express. Capitalized JSX resolves a unique stable template Name or a built-in MDX adapter. Add custom components to this Content Block's Templates before referencing them in MDX. The display label is independent. JSX attributes accept quoted values and bare booleans; expressions such as {false} are unsupported. Legacy ws.element and ws:name forms are compatibility input only. Component namespaces such as $.*, radix.*, and animation.* are unsupported; use direct component identifiers. Matching explicit children overlay designed descendants and keep template styles. A mismatched child structure replaces defaults, an explicit empty pair clears defaults, and a self-closing reference keeps them. Editing inherited default content writes it back as explicit JSX children. Template resolution is live when matching templates are added later. Preserve invalid source and unresolved names, inspect all diagnostics, and reload before retrying a revision conflict. A frontmatter update replaces the complete property map; preserve fields the user did not ask to remove. Store frontmatter images as exact $ref objects; bind editable Image sources to .src with explicit binding.mode:"readwrite" and alt properties to the Asset .description with mode:"read". Omitting the source mode leaves the image visible but not replaceable in Content mode. Only exact direct frontmatter bindings may use mode:"readwrite". After a template rename or deletion, use migrate-content-block-template-references to preview and confirm custom-template JSX and legacy changes across selected MDX files. A confirmed removal unwraps paired references and preserves their authored children; a self-closing reference disappears because it has none.
For an editable MDX article, use the resource to select the Content Block's source Asset (post.data.id), then bind article fields inside the block to its document parameter (document.frontmatter.title), not query-result properties. Inspect the actual document variable name first. Create writable bindings explicitly: update-text uses expressionBindingMode:"readwrite"; bind-props uses binding.mode:"readwrite". These generic tools target persistent designed instances, such as a header outside the MDX body, not MDX-generated instances. The MDX body is editable through its source mapping; merely placing static or query-bound content inside the block does not make it editable. Use exact direct paths; property access is already safe. Direct bindings through a loaded Markdown or MDX $ref ending in #frontmatter save to the referenced file, with its write permissions enforced. Shared-record edits affect every document using that record. Computed expressions and JSON/body references remain read-only. Image replacement is supported: a direct Image source binding with mode:"readwrite" lets the picker replace the frontmatter $ref, while shared Asset metadata is edited in Asset settings. Follow the complete article editability checklist below before handoff.
Content Block completion checklist
For every Content Block creation, migration, or repair—with or without MDX—treat Content-mode editability as a delivery requirement for all content the user expects editors to change. Before implementation, inventory each value, its intended UI control, and its write destination. Choose controls by meaning: date/calendar controls for dates, image pickers for image replacement, and direct text or number controls for reading time. Keep fixed punctuation and units outside a directly bound value element; never mix literal and expression children there. Preserve the existing stored type and wording: if readTime already stores 4 min read, bind that whole string directly instead of assuming it stores only a number. Distinguish protected layout/templates from editable content explicitly. Test each field through Content mode, check the saved project data or source file, reload, restore test values, and record passed/failed/not tested. Testing one heading, inspecting bindings, or successfully writing through MCP does not cover the remaining fields. Report missing controls and unsupported writes as unfinished requirements, not successful delivery.
Complete article editability is required
When the user asks for the whole article to be editable in Content mode, this includes every article-owned value: title, excerpt, author details and links, dates, reading time, categories, hero and inline image sources, alternative text, captions, body text, links, and custom-component content and media. Exclude only designer-owned layout, styling, templates, and shared navigation/footer unless the user asks otherwise. A correct preview, a successful MCP write, or an editable body does not prove this requirement is met.
Before handoff:
- Inventory every article field, its UI control, binding, and source file/field. Header fields outside MDX content are still part of the article and must be editable through the Content Block's document bindings.
- In Content mode, edit every inventoried field through the UI, including choosing a different hero image and editing link destinations and custom-component props. Do not substitute a raw MDX/YAML edit or an MCP write for this check.
- Read the saved source after each edit. Confirm the intended MDX body/frontmatter or referenced author file changed, unrelated content stayed intact, and the edit survives reload. Restore test values and verify restoration.
- Mark each field passed, failed, or not tested. Do not claim the article is fully editable while any required field is failed or untested.
Image replacement is not shared metadata editing. For frontmatter such as featureImage: { $ref: "./images/hero.png" }, bind the Image source directly to document.frontmatter.featureImage.src with binding.mode:"readwrite" using bind-props. In Content mode, Choose source replaces the article’s featureImage.$ref; it does not overwrite the shared Asset’s resolved .src. The resolved URL field stays read-only. Verify the picker, saved reference, and reload—do not infer support from the displayed image alone. Bind alternative text to .description to use the shared Asset description; edit it through Choose source → asset actions → Settings → Description, which affects every use of that Asset. Do not treat a missing write mode as a platform limitation, and do not defer image replacement over a separate shared-description question.
Keep intended editable values separate from display formatting. For reading time, use three inline sibling text elements: static — , one value element bound directly to document.frontmatter.readingTime with expressionBindingMode:"readwrite", and static min read. The value element must contain only that binding, not mixed literal and expression children. Preserve whitespace and the stored field type. Do not concatenate labels or units, use template literals, or add fallbacks/formatting calls to an editable binding. Prefer component formatting controls with a directly bound value. Explain unsupported cases and ask before making an intended editable field read-only; do not trade away editability just to match the display.
Run it from the linked Webstudio project root. The startup status line prints that absolute root; use it for local files such as <project root>/.temp/script.mjs, screenshots, and generated artifacts.
For experiments, pass --dry-run to local-capable mutation calls. Read the computed transaction from meta.session.transaction and its base build version from meta.session.version. Copying a .webstudio folder is not an isolated project clone; .webstudio/config.json still points to the same remote project, so non-dry-run mutations can commit to that project.
Startup marks cached ProjectSession data stale so MCP tools read the current Builder dev build.
After startup, use focused discovery tools with concrete JSON. For delegated design-system or “use every component” tasks, start with exactly one command: webstudio workflow.next '{"goal":"design-system-page"}'; report the returned checkpoint to the parent/user and stop until continued. For other tasks, read meta.index first. From a shell, webstudio mcp list-tools is a concise alias for the initial tool catalog. Then call shortcuts such as webstudio meta.guide '{"brief":"Create a design system page using every component"}', webstudio workflow.next '{"goal":"design-system-page"}', webstudio meta.get-more-tools '{"tools":["insert-fragment"]}', webstudio components.list '{"source":"all"}', webstudio components.summary, webstudio components.search '{"brief":"radix select"}', webstudio components.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}', webstudio templates.list, and webstudio templates.get '{"component":"@webstudio-is/sdk-components-react-radix:Select"}'. Use webstudio mcp single-op-call when you need the explicit MCP form. Prefer insert-fragment for authored/styled sections; use insert-component only when inserting one automatic component template. In JSX, use ws:style={css\...`}for styles,class/forinstead ofclassName/htmlFor, ActionValuefor actions instead of JavaScript functions such asonClick={() => ...}, only JSON-compatible plain prop values, and no host globals or dynamic code APIs. For bounded multi-step shell work, run inline JSON like webstudio mcp run '[{"tool":"meta.index"},{"tool":"components.search","input":{"brief":"button"}}]'; this reuses one CLI session without raw JSON-RPC. For larger batches, write { "calls": [{ "tool": "..." }] }to.temp/mcp-calls.jsonand runwebstudio mcp run .temp/mcp-calls.json. If any call returns checkpoint.required, mcp runstops immediately before later calls; report the checkpoint and callcheckpoint.ack {"reported":true,"continueAfterReport":true,"summary":""}before continuing. For design-system or “use every component” tasks, callworkflow.next {"goal":"design-system-page"}for the next bounded phase, report its checkpoint, wait until the parent/user continues, callcheckpoint.ack {"reported":true,"continueAfterReport":true,"summary":""}, then run only that phase. Start coverage phases with compactwebstudio components.coverage-plan, checkpoint, then request component coverage details with components.coverage-plan {"detail":"roots"}orcomponents.coverage-plan {"detail":"parts"}. Do not pass detailtolist-pages; use list-pages {}orget-page-by-pathfor page lookup. Read MCP overview resourceswebstudio://project/guide, webstudio://project/tools-overview, and webstudio://project/components-overviewwhen useful. Read full resourceswebstudio://project/toolsandwebstudio://project/components` only when focused tools are insufficient; do not dump or parse full discovery JSON for common lookup.
After startup, MCP clients discover capabilities with tools/list, resources/list, meta.index, meta.guide, and meta.get-more-tools.
stdout is reserved for MCP JSON-RPC messages while the server is running.
The server advertises MCP logging capability and sends sparse notifications/message logs for ready state and tool lifecycle checkpoints such as tool preview.start started, tool preview.start still running after 10000ms, and tool preview.start succeeded in 1234ms. It also writes the same sparse lifecycle status lines to stderr, prefixed with [webstudio mcp], including a final ready line. Treat the process as healthy and long-running after either ready signal; surface tool lifecycle logs as progress checkpoints and interact through MCP JSON-RPC on stdin/stdout.
webstudio mcp single-op-call also writes sparse lifecycle lines to stderr for each one-shot call. Use those stderr lines as progress checkpoints and parse stdout as JSON on both success and failure. Failed one-shot calls print { "ok": false, "error": { "code": "...", "message": "..." }, "meta": ... } to stdout and exit nonzero. If a one-shot call returns checkpoint.required, read-only discovery remains available, while later mutations fail with CHECKPOINT_REQUIRED until you report the checkpoint and call webstudio mcp single-op-call checkpoint.ack '{"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}'.
webstudio mcp run also writes sparse lifecycle lines to stderr and prints one JSON result on success or failure. It stops at the first failed call or checkpoint requirement, including CHECKPOINT_REQUIRED, and preserves partial results so delegated agents can report exactly where they stopped.
When report-issue is available, use it when the user explicitly asks to report a problem. Also use it automatically after a Webstudio-controlled tool crash, hang, malformed result, misleading success, repeated failure of the same documented operation, failed documented recovery, or required undocumented workaround. Do not automatically report expected confirmation/checkpoint flow, a clearly explained invalid input, missing permissions, PROJECT_SESSION_BUSY, a recovered version conflict, rate limiting, cancellation, or an offline environment. Write a complete technical report with the generalized user story, attempted workflow, expected behavior, actual result, recovery attempts, impact, technical context, acceptance criteria, exact model identifier, and reasoning effort. The CLI attaches the project ID and recognized entity IDs from the failed tool input; do not copy additional IDs into the authored text. Never include names, usernames, emails, phone numbers, organizations, domains, URLs, IP addresses, local paths, credentials, tokens, customer content, other exact unique values, or raw contextual tool data.
If a mutation returns an unclear transport or response error, make one read-only check to see whether it committed and include that outcome in the report. For browser startup failures, include the selected browser family, whether fallback was attempted, and any shown exit signal or code, but never an executable path. The CLI adds bounded failure diagnostics automatically; do not paraphrase missing values as facts.
If you are running as a delegated or non-streaming agent whose parent cannot see live stderr/stdout, do not batch many MCP calls silently and do not run long shell loops of shortcut or webstudio mcp single-op-call commands. Treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one shortcut command such as webstudio meta.index or one explicit webstudio mcp single-op-call command, return a concise checkpoint with that command/result, and wait for the parent to continue. Do not take a broad task such as creating a full design-system page as one execution unit. Call workflow.next {"goal":"design-system-page"}, report the returned phase/checkpoint, wait until the parent/user continues, call checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}, complete exactly that bounded phase, and return: discovery, page creation, one dry-run JSX section, one committed JSX section, one components.coverage-insert-next call, or one presentation pass. Phase commands do not include nextPhase in their own output. After the parent continues, acknowledge the previous checkpoint first, then call workflow.next with the next phase. For all-component design-system pages, checkpoint after workflow planning, discovery, page creation, call components.coverage-insert-next once before checkpointing again, then finish with the presentation-pass workflow phase.