# swebsy/MCP [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/swebsy/MCP  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1871  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/swebsy-mcp

## Description
Build and edit real websites in Swebsy Studio from your coding agent — no per-token AI fees.

## Tools
Capabilities this server exposes over MCP:

- **swebsy_replace_page_content** — Replace ALL top-level sections of the CURRENTLY SELECTED page with a generated list of components. This OVERWRITES the page — it does NOT create a new page (use `create_page`) and does NOT append a single section (use `add_section`). Use when the user asks to build/replace/redesign an entire page. Each top-level component should be wrapped in a container.
- **swebsy_create_page** — Create a NEW blank page in the project and (by default) select it. Returns the new page's id and fileName. The page starts nearly empty — fill it with `replace_page_content` or `add_section`, and point a navbar/link at it with `link_page`. Use THIS to add an additional page; use `replace_page_content` (NOT this) to overwrite the current page's content.
- **swebsy_link_page** — Point an existing link at a project page — the same wiring the UI's 'Link to' picker does. Pass the link's `targetId` or `targetPath` (from `read_page`) and the target `page` (id or name). For a navbar link this sets its page target so the href and active state stay in sync; for a plain link or button it sets href to the page's ./slug.html. Use after `create_page` to wire a navbar to the new page.
- **swebsy_update_page** — Rename a page and/or change its URL slug — the Pages panel's rename. Links that pointed at the old `./slug.html` on every page follow the new slug. The home page's `index` slug is locked (its display name can still change).
- **swebsy_duplicate_page** — Copy a page (content, classes and styles) into a new page and select the copy. Returns the new page's id and fileName. Use it to start a page from an existing layout instead of rebuilding it.
- **swebsy_delete_page** — Delete a page. The home page (index) and a site's last page can't be deleted. Links to the deleted page are left in place — repoint them with `link_page` or delete them.
- **swebsy_add_section** — Insert a new section into the current page. Use for adding discrete sections (hero, features, pricing, CTA) to an existing page. Supply exactly one of `component` (a component tree) or `html` (one root element). Appends to the end by default; to place it somewhere specific, pass `position` plus the `targetPath` of the component to place it next to.
- **swebsy_edit_section** — Modify an existing component. By default this edits the selected component. To edit a component identified by `read_page`, provide its `targetId` (preferred — survives other edits) or `targetPath`; an explicit target overrides the canvas selection. Preferred: provide `component` — the full replacement component tree (compact DSL OK), best for structural changes. Alternative: provide `html` — the complete modified HTML string. Fallback: provide `patch` — JSON Patch (RFC 6902) for tiny single-property tweaks. Supply exactly one. Preserve existing IDs: an id kept in the edit keeps the styles attached to it; an id you drop loses them. The result's `id` is the component's id after the edit (a replacing edit can give it a new one). `changed: false` means the page's HTML/CSS/JS came out identical, so the edit did not show up; `success: false` means a patched attribute is not what the page exports.
- **swebsy_delete_section** — Remove a component from the current page entirely. Use this instead of emptying a section's contents — an emptied section leaves a stray blank div on the page. Deletes the selected component by default; pass `targetId` or `targetPath` (from `read_page`) to delete a component you did not select.
- **swebsy_move_section** — Move a component to just before or after another component on the current page — reorder sections, swap columns, lift a CTA above the footer. The component keeps its id, classes and id-styles. ALWAYS use this to reorder; delete + re-add loses the component's styles. Name each side by id (`targetId`/`anchorId`) or by path (`targetPath`/`anchorPath`).
- **swebsy_wrap_section** — Wrap a run of sibling components in one new element, optionally with a semantic tag — e.g. put everything between the navbar and footer in `<main>`, or a footer symbol in `<footer>`. The wrapped components keep their ids, id-styles and symbol links. ALWAYS use this to add a wrapper; re-sending the components through `edit_section`/`replace_page_content` loses their styles. Paths shift — call `read_page` before the next path-based edit.
- **swebsy_duplicate_section** — Copy a component (with its classes and styles) and insert the copy right after it. Paths after it shift by one — call `read_page` before the next path-based edit (ids don't shift).
- **swebsy_insert_block** — Insert a pre-built block from the catalog and optionally customize its content. STRONGLY preferred over generating from scratch when a matching block exists. The block re-themes on insert — its colour and font classes resolve against THIS site's theme, so the result is meant to differ from the catalog thumbnail (a screenshot of the block in the template it came from).
- **swebsy_update_settings** — Update site settings — SEO title/description, site URL, structured data (JSON-LD), per-page SEO overrides, language/direction, theme tokens (light + dark), type scale, animation defaults, Google and uploaded fonts, dark mode toggle, site-wide custom CSS for component-level restyling (globalTheme.customTailwindConfig), favicon, robots.txt/sitemap/service worker/security headers/image optimization (performance), analytics ids, custom head/body code (advanced), the "Made with Swebsy" badge (branding) and the deploy target (deploy). Provide ONLY the fields that change. `general`/`seo` are SITE-WIDE; use `page` to change ONE page. Also used to match the theme to a reference IMAGE's vibe: sample its palette into brand/surface tokens and ALWAYS set BOTH light and dark variants.
- **swebsy_commit_design_direction** — Commit this site to a specific visual direction, and apply it (fonts, type roles, palette swatches). Call this ONCE, BEFORE generating a new site's first page — a site with no committed direction has nothing for later edits to stay consistent with, and the result drifts to generic. Prefer a `directionId` from the sampled menu; supply the `custom` fields only when the user's brief clearly calls for something the menu doesn't cover. Not needed when editing a site that already has a direction.
- **swebsy_animate_page** — Apply Swebsy's built-in scroll-reveal animation in one step — a smart, per-section staggered entrance on headings, text, images, buttons, and cards (navbars/footers skipped). Prefer this over hand-placing animate-* classes whenever the user asks to animate the page or site, or wants a consistent reveal.
- **swebsy_read_page** — Read the current page structure: each line shows a component's target path and its `#id`. edit_section, delete_section, move_section, duplicate_section and link_page take either — prefer the id (`targetId`), which survives moves and inserts; other tools take the path. Use the id only to target; don't copy auto ids into markup. Call this BEFORE editing a named or relative page component that is not the current selection. The default `sections` read lists every top-level section with its target path — enough to pick the one to edit. To find a nested element (a link, button, card) pass that section's `targetPath` plus `depth` — one call instead of drilling down level by level. When copying content between components, use `detail: full` WITH the `targetPath` of the one section you're copying, not a whole-page read. Also call it AFTER applying edits to verify the result.
- **swebsy_get_skill** — Load deep, on-demand guidance for a specific area before acting on it (e.g. before adding animations, composing a new page, writing copy, building forms, editing the nav, or reusing components with symbols). Returns the full instructions for that skill.
- **swebsy_publish** — Publish the open site to Swebsy Hosting, free, at its own swebsy.site address, and return the live URL. Call it ONLY after the user has said yes to publishing in this conversation, and ask again before every publish, a republish included: an earlier yes doesn't carry over. If it can't go live straight away (no account yet, a plan limit, something to check), nothing goes out yet: Studio opens its Publish screen and the result says what to tell the user. When it says Studio finishes publishing from there, don't call publish again; the site goes live once the user is done.
- **swebsy_start_pairing** — Start a pairing session. Returns a single-use `pairUrl` — give it to the user to click; opening it connects their Studio tab automatically. (Also returns the raw `code`/`port` for manual entry.)
- **swebsy_status** — Report bridge status, siteName, selected page, and editorReady, plus a short theme summary (fonts, default color mode, brand colors). After creating or opening a site, wait until editorReady is true and siteId matches the expected site before editing.
- **swebsy_list_pages** — List the project's pages (id, name, fileName, section count, which one is selected). Call this instead of guessing a page name for select_page or link_page.
- **swebsy_list_templates** — Refresh and list installed site templates with names, descriptions, tags, fonts, preview URLs, and thumbnail URLs. Works from Home or Studio.
- **swebsy_create_site** — Create a site and open it in Studio. Pass name to set its internal Studio/Home name (default "My Website"). Omit templateId for Swebsy's standard blank site; provide an installed template ID to import that template unchanged. Then poll swebsy_status until editorReady is true and siteId matches before editing.
- **swebsy_list_sites** — List saved sites newest-first as metadata only: IDs, internal names, status, timestamps, template ID, page count, and whether each site is open.
- **swebsy_open_site** — Open a saved site by ID in the paired tab and return its metadata. Idempotent if it is already open. Poll swebsy_status for the expected siteId and editorReady before editing.
- **swebsy_rename_site** — Rename a saved site's internal Studio/Home name. This does not change its SEO or public title settings.
- **swebsy_select_page** — Select a page in the connected Studio project.
- **swebsy_read_selection** — Read the currently selected component (type, classes, attributes, text). Secrets are never surfaced.
- **swebsy_list_symbols** — List the project's SYMBOLS (reusable components that stay in sync across every page). Returns each symbol's id, name, component type, instance count, and how many pages use it, plus a `health` report of BROKEN linkage: `orphans` (copies whose main was deleted — editing them changes nothing elsewhere), `unregistered` (instances the main doesn't list back, so edits propagate one way only) and `ghosts`. Repair any of it by calling promote_to_symbol on one affected section. Use before add_symbol_instance to find the symbol id.
- **swebsy_promote_to_symbol** — Promote an existing component into a reusable SYMBOL so it can be shared, in sync, across pages. Pass its `targetPath` from read_page (e.g. the navbar or the CTA band). Also REPAIRS broken linkage (see list_symbols → health): re-promoting an orphaned copy rebuilds its main and re-links every other copy of it, and re-promoting a symbol registers instances it had lost. Returns the symbol id (for add_symbol_instance) and a `repaired` count; copies whose structure has diverged too far are reported as `detached` — delete_section + add_symbol_instance those instead.
- **swebsy_add_symbol_instance** — Add a linked INSTANCE of an existing symbol (see list_symbols) to the CURRENT page. The instance stays in sync with the symbol main and every other instance — the way to reuse one navbar/footer/CTA across pages. Select the target page with select_page first.
- **swebsy_detach_symbol** — Turn ONE symbol instance on the current page back into a plain component, so it can be edited on its own. The symbol and its other instances stay linked. Use it when one page needs a variant of the shared navbar/footer.
- **swebsy_rename_symbol** — Rename a symbol (the name shown in the Symbols panel).
- **swebsy_delete_symbol** — Delete a symbol. Every instance is DETACHED first and stays on its page as a plain component — nothing disappears from the site. To also remove the copies, delete_section them.
- **swebsy_undo** — Revert your own last editing tool call(s) this session (add/edit/delete/move/duplicate_section, insert_block, update_settings, page tools…), newest first. Does NOT undo symbol or asset tools. Refuses (returns `blocked`) when a page, CSS or settings it would restore has been edited since, so hand edits are never overwritten. Paths may shift — call read_page afterwards.
- **swebsy_redo** — Re-apply tool calls reverted by swebsy_undo, oldest-undone last. Cleared by any new edit.
- **swebsy_get_builder_guide** — Load the static Swebsy builder guidance (component system, theme classes, conventions) that the in-app AI Builder is primed with.
- **swebsy_list_skills** — List the available deep-guidance skills (animation, page-composition, copywriting, forms, nav) with one-line summaries.
- **swebsy_list_blocks** — List the pre-built block catalog (ids + labels) available to insert_block.
- **swebsy_capture** — Capture a styled screenshot of the current page at a fixed viewport, written under .swebsy-agent/screenshots/. Returns the file path. Scope it with `targetPath` when verifying ONE section — a whole-page PNG downscales so far that component detail is unreadable.
- **swebsy_list_assets** — List managed assets in the open site with whole-project usage counts. References are checked across every page, shared symbols, styles, and site settings. Use imagesOnly:true and unusedOnly:true before deleting unused gallery images.
- **swebsy_upload_asset** — Upload a local image, font, video, audio or PDF file into the open site and return its `assetId`, `src` and a `usage` snippet. Images go in the asset library for `image` components, video for `video` components (`attributes.src`), audio for `audio`, PDFs as a link `href`; fonts are stored for `update_settings` fonts.custom. This is the ONLY way to get your own imagery (screenshots, logos, textures, mockups) into a site — an `image` with an empty src gets a random stock photo instead. Reads the file from the agent's own filesystem, so pass a path you can see (for example a screenshot you just captured). The asset is stored in the project and travels with static export and project JSON. Pass `path` or `paths` (exactly one). Several files: pass `paths` (up to 25) instead of `path` for one call that returns a compact `{assets: {basename: src}, failed: {basename: reason}}` map.
- **swebsy_delete_asset** — Delete one managed asset from the open site's asset gallery. By default this refuses assets referenced by any page, shared symbol, style, or site setting; call swebsy_list_assets first. force:true also clears live component references and should be used only when that is explicitly intended.
- **swebsy_export** — Export the site to .swebsy-agent/exports/. Static files via the site exporter and/or the project JSON (with assets). Returns `outDir`, the exported page paths, and per-kind file counts — verify a build by grepping those HTML files.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp": {
    "command": "npx",
    "args": ["-y","@swebsy/mcp"],
    "env": {
      "SWEBSY_AGENT_PORT": "",
      "SWEBSY_AGENT_DIR": "",
      "SWEBSY_APP_URL": "",
      "SWEBSY_NO_OPEN": ""
    }
  }
}
```

**Requires environment variables:** `SWEBSY_AGENT_PORT`, `SWEBSY_AGENT_DIR`, `SWEBSY_APP_URL`, `SWEBSY_NO_OPEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What swebsy/MCP MCP server does

swebsy/MCP exposes Swebsy Studio as a set of tools for MCP-compatible coding agents. An agent can discover templates, create or open sites, rename projects, inspect the page tree, edit sections and content, switch between pages, and export a completed project. It can also configure site-level options such as SEO, favicons, fonts, analytics, robots.txt, and deployment targets.

The server is intended for building real websites in Swebsy rather than generating text-only plans. Swebsy exports HTML, CSS, and JavaScript files, so the resulting project can be hosted outside Swebsy.

## How it works

The package runs as a local stdio MCP server and starts a relay on the local machine. The relay communicates with an open Swebsy Studio browser tab over `127.0.0.1`. On the first tool request, the server can open a pairing flow and connect Studio; subsequent sessions reuse a saved session file. The Studio tab must remain available while tools are being used. A sleeping browser tab can cause `tab_unresponsive` results until it is activated.

After creating or opening a site, an agent should poll `swebsy_status` until the expected site ID is present and the editor reports that it is ready. Multiple coding agents can use one paired tab when they share the same relay port. Commands are serialized so the editor processes one operation at a time, while results, screenshots, and exports are routed to the requesting agent. Pairing another Studio tab replaces the previous pairing.

Studio removes secrets such as API keys, deployment tokens, and chat history before data crosses the bridge. Non-secret content is still handled by the coding agent and its applicable service and privacy policies.

## Setup and configuration

The package can register itself with supported agents using:

```bash
npx -y @swebsy/mcp setup
```

Manual registration is also available through each client's MCP configuration. The package supports setup examples for Claude Code, Codex, Cursor, Windsurf, VS Code with GitHub Copilot, and Cline. A local source build can be used by pointing an agent at `dist/server.js` instead of invoking the npm package.

The main configuration variables are:

- `SWEBSY_AGENT_PORT`: local relay port; defaults to `37373`.
- `SWEBSY_AGENT_DIR`: directory for screenshots and exports; defaults to `.swebsy-agent` in the workspace.
- `SWEBSY_APP_URL`: Studio origin used in pairing links; useful for a local or self-hosted Studio deployment.
- `SWEBSY_NO_OPEN`: set this variable to prevent automatic browser opening during pairing.

To pair manually, run `swebsy_start_pairing` and open the returned link in the browser containing Studio. The raw code and relay port are also returned for fallback pairing.

## Tools and capabilities

The available `swebsy_*` tools cover site and editor operations, including:

- Listing installed templates and saved-site metadata.
- Creating blank sites or importing templates.
- Opening sites by ID and renaming their internal Swebsy names.
- Reading page structure, adding sections, editing content, and creating or linking pages.
- Inserting blocks and managing reusable symbols, including per-instance content with shared styling.
- Applying site settings for SEO, favicons, fonts, analytics, robots.txt, and deployment targets.
- Capturing screenshots at selected viewport sizes.
- Exporting the finished project.
- Checking connection and editor readiness with `swebsy_status`.

Site listings return metadata only; they do not include page content, thumbnails, assets, revisions, or settings.

## Limitations and notes

The browser tab must stay open and responsive. One Studio tab can be paired with one broker at a time, although several agents can share that paired tab. Site IDs are authoritative, and duplicate internal site names are allowed. The package is designed for coding agents running on the user’s machine; ChatGPT and the Claude app use a separate hosted connector flow rather than this package.

_Full upstream README: https://allmcps.com/mcp/swebsy-mcp/readme_