shopify-iframe-dev-mcp

shopify-iframe-dev-mcp.js is a single-file MCP server for inspecting and debugging a Shopify embedded app from an MCP client. It runs over stdio and exposes a localhost WebSocket bridge that a browser page can connect to.

The browser bridge client is embedded in shopify-iframe-dev-mcp.js as readable JavaScript source so the injected snippet remains inspectable.

What it does

• Maintains browser sessions connected through the localhost bridge
• Lets the MCP client choose the active browser session
• Executes arbitrary JavaScript inside the connected iframe page
• Returns a copy-paste browser-console snippet with the correct bridge port already embedded
• Falls forward to the next free localhost port if the preferred bridge port is already taken

Requirements

• Node.js 18 or newer
• @modelcontextprotocol/sdk installed via npm install
• A browser tab or iframe where you can paste the bridge snippet

Installation

npm install

Running the server

From the repository root:

npm start

The MCP transport is stdio. The browser bridge binds to 127.0.0.1.

Environment variables:

• BRIDGE_PORT Default: 17373 Preferred starting port for the browser bridge.
• BRIDGE_EVAL_TIMEOUT_MS Default: 10000 Timeout in milliseconds for bridge_eval.
• BRIDGE_TOKEN Optional. Overrides the default randomly generated bridge token used to authenticate browser connections.

If BRIDGE_PORT is already in use, the server increments upward until it finds a free port.

MCP client configuration

Configure your MCP client to launch the server with:

node shopify-iframe-dev-mcp.js

If your client needs a structured command configuration, the equivalent shape is:

{
  "command": "node",
  "args": ["shopify-iframe-dev-mcp.js"]
}

If the MCP client supports package execution, you can also point it at the installed CLI binary name instead of the script path.

Exposed tools

• bridge_status Returns bridge host, resolved port, requested port, auth mode, session count, and current active session.
• bridge_browser_snippet Returns wsUrl plus a minified snippet value to paste directly into the browser console.
• bridge_list_sessions Lists connected browser sessions and their metadata.
• bridge_select_session Marks one connected session as the active target for evals.
• bridge_eval Runs arbitrary JavaScript inside the selected browser session.

Typical flow

1. Start the server.
2. Call bridge_browser_snippet.
3. Copy the returned snippet value exactly as-is.
4. Paste it into the embedded app iframe browser console.
5. Call bridge_list_sessions.
6. Optionally call bridge_select_session.
7. Call bridge_eval.

Example bridge_eval payload:

{
  "code": "return { title: document.title, url: location.href };",
  "timeoutMs": 5000
}

Health endpoint

The bridge also exposes a local HTTP health endpoint at:

http://127.0.0.1:<resolved-port>/health

It returns the resolved bridge host, resolved bridge port, requested bridge port, and current session state.

Security model

• The browser bridge listens only on 127.0.0.1.
• Browser connections must present a bridge token.
• bridge_browser_snippet includes the correct token and resolved port automatically.
• Anyone with access to that snippet can connect to the local bridge for the lifetime of the server process.
• bridge_eval executes arbitrary JavaScript in the connected page context.

Notes

• This is a development-only tool.
• The bridge is local only and does not bypass browser same-origin restrictions outside the connected page context.