Etch Agent Bridge

Local Chrome extension plus MCP server for controlling the Etch builder from MCP-capable agents such as Claude, Codex, opencode, Cursor, or similar tools.

This is not an AI chat product and it does not need model API keys. Your agent client provides the AI model. This project only connects that client to an already-open Etch builder tab through the Etch Public API.

What You Get

• A Chrome MV3 extension that can see Etch builder tabs only when the URL contains etch=magic.
• A local stdio MCP server that exposes Etch tools to your agent.
• A local WebSocket relay on ws://127.0.0.1:8787 so several MCP clients can share the same browser extension.
• Direct Etch edits for blocks, styles, loops, components, navigation, history, UI color scheme, and document saving.

Prerequisites

• Git.
• Bun 1.x or newer: https://bun.sh/docs/installation
• Chrome, Chromium, Brave, Edge, or another Chromium browser that supports unpacked extensions.
• An authenticated WordPress admin session with Etch installed.
• An Etch builder page where window.etch is available.
• One MCP-capable client, for example Claude Code, Claude Desktop, Codex, opencode, Cursor, or Windsurf.

Install And Build

Clone the repo and build the extension:

git clone https://github.com/honestlydesign/etch-agent-extension.git
cd etch-agent-extension
bun install
bun run build

The browser extension build is created at:

apps/extension/dist

Load The Extension

1. Open chrome://extensions in your Chromium browser.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select the apps/extension/dist folder from this repo.
5. Keep the extension installed while you use an MCP agent.

After every bun run build, reload the extension on chrome://extensions and reload the Etch builder tab.

The extension has a status popup only. It does not contain an editor UI.

Open An Etch Target

1. Log into WordPress in the same browser.
2. Open the Etch builder for the page or template you want to edit.
3. Add etch=magic to the URL.

Examples:

https://example.test/wp-admin/admin.php?page=etch-builder&etch=magic
https://example.test/wp-admin/admin.php?page=etch-builder&post=123&etch=magic

If the URL already has query parameters, use &etch=magic. If it has no query parameters, use ?etch=magic.

The extension intentionally ignores pages without etch=magic.

Configure MCP

Each MCP client should launch the same local server:

cd /ABS/PATH/etch-agent-extension && bun run apps/mcp/src/index.ts --client-name <client-name>

Use the absolute path to your cloned repo. If the MCP client cannot find bun, run which bun and replace bun in the command with the absolute Bun path.

The first MCP server process starts the relay host on port 8787. Later MCP clients connect through that existing relay. This means Claude, Codex, and opencode can all have this MCP configured at the same time. Only one agent should mutate the Etch canvas at a time.

The JSON examples below show only the relevant MCP entry. If your client already has a config file, merge the etch-agent entry into it instead of replacing the whole file. Do not commit project MCP config with your private absolute path.

Claude Code Or Claude Desktop

For Claude Code, use a project .mcp.json or your normal Claude MCP config. For Claude Desktop, put the same mcpServers block in claude_desktop_config.json.

{
  "mcpServers": {
    "etch-agent": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name claude"
      ]
    }
  }
}

Restart Claude after changing the config.

Codex

Add an MCP server entry to ~/.codex/config.toml:

[mcp_servers.etch-agent]
command = "bash"
args = ["-lc", "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name codex"]

Restart Codex after changing the config.

opencode

Add a local MCP entry to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "etch-agent": {
      "type": "local",
      "command": [
        "bash",
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name opencode"
      ]
    }
  }
}

Restart opencode after changing the config.

Cursor, Windsurf, And Other MCP Clients

Most MCP clients use the same JSON shape as Claude:

{
  "mcpServers": {
    "etch-agent": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name cursor"
      ]
    }
  }
}

If your client supports a cwd field, you can also set cwd to the repo path and use command: "bun" with args: ["run", "apps/mcp/src/index.ts", "--client-name", "your-client"].

Verify The Setup

1. Start or restart your MCP client.
2. Open an Etch builder tab with etch=magic.
3. Open the extension popup. It should show relay and target status.
4. Ask your agent to list Etch targets or inspect the selected block.

Useful first prompt:

Use the Etch MCP tools to list available targets, inspect the selected block, and do not save anything.

If the agent sees a target, the extension and MCP server are connected.

Save Behavior

Most mutation tools change the Etch canvas immediately but do not persist to the WordPress database until etch_save_document is called.

The agent should call etch_save_document only when you explicitly ask it to save. Until then, browser navigation or document switching can discard unsaved edits, depending on Etch behavior.

Component upserts and component deletes are different: Etch persists them immediately through the component API.

Troubleshooting

No Etch target appears:

• Make sure the builder URL contains etch=magic.
• Make sure the WordPress session is authenticated in the same browser.
• Make sure the extension is loaded from apps/extension/dist.
• Reload the extension and then reload the Etch builder tab.
• Ask the agent to call etch_list_targets again.

The MCP client starts but bun is not found:

• Run which bun.
• Replace bun in the MCP config command with that absolute path.
• Restart the MCP client.

Port 8787 is busy:

• If another Etch Agent Bridge MCP process is running, that is expected. New clients connect to it.
• If a different process owns the port, stop that process and restart the MCP client.
• --relay-port <port> exists for tests, but the browser extension expects 8787 by default.

The extension is connected but Etch tools fail:

• Confirm the page is an actual Etch builder page.
• Confirm window.etch exists in that builder session.
• Reload the builder after reloading the extension.

Changes are not visible after editing code:

• Run bun run build.
• Reload the unpacked extension.
• Reload the Etch builder tab.

Development Commands

bun install
bun run build
bun run typecheck
bun run test
bun run dev:mcp

bun run dev:mcp starts the MCP server directly for local development. In normal use, your MCP client starts the server from its config.

Architecture

• apps/extension is the Chrome MV3 extension with a status popup, background relay connection, isolated content script, and MAIN-world window.etch bridge.
• apps/mcp is the stdio MCP server. Each running MCP process either hosts the relay on ws://127.0.0.1:8787 or connects to the existing relay as a client.
• packages/shared contains shared schemas, target types, bridge protocol, activation logic, and MCP tool names.
• skills/etchapi/SKILL.md describes the agent workflow for agents working inside this repo.

Tool Coverage

Area	Tools
Targets and status	etch_list_targets, etch_get_active_target, etch_set_active_target, etch_get_status, etch_get_last_apply_result
Blocks	etch_get_selected_block, etch_get_document_tree, etch_get_block_json, etch_find_blocks, etch_insert_blocks, etch_replace_block, etch_update_block, etch_mutate_block_attributes, etch_duplicate_block, etch_move_block, etch_delete_block
Styles	etch_list_styles, etch_apply_style_patch, etch_delete_style, etch_get_style_variable, etch_remove_style_variable
Components	etch_list_components, etch_get_component_json, etch_upsert_agent_component, etch_delete_agent_component
Navigation	etch_list_posts, etch_list_templates, etch_open_post, etch_open_template, etch_get_navigation_context
Loops	etch_list_loops, etch_upsert_loop, etch_delete_loop, etch_bind_loop_to_block
History and UI	etch_undo, etch_redo, etch_get_color_scheme, etch_set_color_scheme
Save	etch_save_document

Fields and global stylesheets are not implemented in this bridge.

Validation Policy

This bridge is a thin pass-through to the Etch Public API. The MCP layer and page-bridge layer validate the structural shape of payloads with Zod, but they do not try to decide which content is safe or valid for Etch.

• Selectors, class names, component keys, loop keys, CSS variable names, text, attribute values, CSS values, and JSON loop data are passed through.
• Block types are forwarded to Etch. Etch is the source of truth for supported block types, tags, attributes, and payload shapes.
• If Etch rejects a payload, the window.etch error is returned through the MCP tool result.

Mutations apply directly to the Etch canvas. Use etch_undo or etch_redo for Etch history operations, and use etch_save_document only when the document should be persisted.