Skip to main content
@mcp-b/webmcp-local-relay connects WebMCP tools running in browser tabs to desktop MCP clients (Claude Desktop, Cursor, Claude Code, Windsurf) via a localhost WebSocket relay and stdio transport. 
npm: @mcp-b/webmcp-local-relay
license: MIT
node: >= 22

​
Architecture

Browser Tab                          Local Machine
┌──────────────────────┐             ┌──────────────────────┐
│                      │  WebSocket  │                      │
│   Website with       ├────────────▶  webmcp-local-relay   │
│   WebMCP tools       │  localhost  │   (MCP server)       │
│                      │             │                      │
└──────────────────────┘             └──────────┬───────────┘
                                                │
                                          stdio │ JSON-RPC
                                                │
                                     ┌──────────▼───────────┐
                                     │                      │
                                     │   Claude / Cursor /  │
                                     │   any MCP client     │
                                     │                      │
                                     └──────────────────────┘
The relay has four layers:
LayerDescription
LocalRelayMcpServerMCP server exposing static and dynamic tools over stdio
RelayBridgeServerWebSocket server managing browser connections and routing calls
Widget iframeHidden iframe injected by embed.js into the host page
Host pageThe webpage with WebMCP tools registered on navigator.modelContext
For a conceptual discussion of transports and bridges, see Transports and Bridges.

​
Installation

Add this JSON block to your MCP client configuration: 
{
  "mcpServers": {
    "webmcp-local-relay": {
      "command": "npx",
      "args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
    }
  }
}
You can also run the relay directly: 
npx @mcp-b/webmcp-local-relay
A .mcpb bundle file is available from GitHub Releases for Claude Desktop (double-click to install).

​
Minimal example

​
CLI options

webmcp-local-relay [options]

  --host, -H               Bind host (default: 127.0.0.1)
  --port, -p               WebSocket port (default: 9333)
  --widget-origin          Allowed host page origin(s), comma-separated (default: *)
  --allowed-origin         Alias for --widget-origin
  --ws-origin              Alias for --widget-origin
  --help, -h               Show help

# Custom port
npx @mcp-b/webmcp-local-relay --port 9444

# Restrict to trusted origins
npx @mcp-b/webmcp-local-relay --widget-origin https://myapp.com,https://other.com

​
Static management tools

The relay always exposes four management tools:
ToolDescription
webmcp_list_sourcesLists connected browser tabs with metadata: tab ID, origin, URL, title, icon, tool count
webmcp_list_toolsLists all relayed tools with source info
webmcp_call_toolInvokes a relayed tool by name with JSON arguments (for clients that do not support dynamic tool registration)
webmcp_open_pageOpens a URL in the default browser or refreshes a connected source page by matching origin

​
Dynamic tool registration

Tools registered on webpages are forwarded to the MCP server as first-class tools. Tool names are sanitized to the character set [a-zA-Z0-9_]. When multiple tabs register a tool with the same name, a short tab-ID suffix disambiguates them:
SituationTool name
Single providerget_issue
Multiple providerssearch_ed93, search_a1b2
Tools appear and disappear as tabs open, reload, and close.

​
Browser embed

Add a script tag to expose a page’s WebMCP tools to the relay: 
<script src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"></script>
If the page already registers tools on navigator.modelContext, they are picked up automatically. To use a custom relay port: 
<script
  src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"
  data-relay-port="9444"
></script>
The embed script injects a hidden iframe that opens a WebSocket to the relay on localhost. Tools are discovered via navigator.modelContext (or navigator.modelContextTesting as fallback) and forwarded to the relay.

​
Reconnection and client mode

The widget reconnects automatically using exponential backoff (1.5x multiplier) from 500ms up to 3000ms, stopping after 100 attempts. When a second relay instance starts and the port is in use (EADDRINUSE), it falls back to client mode. In client mode the relay connects as a WebSocket client to the existing server relay and proxies tool operations through it. If the server relay stops, the client promotes itself back to server mode. This lets multiple MCP clients share the same browser connections.

​
Runtime compatibility

The relay supports pages using:
  1. @mcp-b/global (recommended)
  2. @mcp-b/webmcp-polyfill with navigator.modelContextTesting
The browser embed uses navigator.modelContext.listTools + callTool when present, and falls back to navigator.modelContextTesting.listTools + executeTool.

​
Security

  • Binds to 127.0.0.1 by default (loopback only).
  • Default allowedOrigins is *, permitting any browser page to connect. Use --widget-origin to restrict which host page origins can register tools.
  • --widget-origin validates the host page origin reported in the browser hello message, not the iframe origin.
  • Any local process can connect regardless of origin restrictions.

​
Exported API

The package exports the following for programmatic use:
ExportKindDescription
LocalRelayMcpServerClassMCP server with stdio transport and dynamic tool sync
LocalRelayMcpServerOptionsTypeConstruction options
RelayBridgeServerClassWebSocket relay managing browser connections
RelayBridgeServerOptionsTypeBridge server options
RelayRegistryClassMulti-source tool aggregation and deduplication
AggregatedToolTypeA tool resolved across multiple sources
SourceInfoTypeMetadata about a connected browser tab
sanitizeNameFunctionSanitizes a tool name to [a-zA-Z0-9_]
buildPublicToolNameFunctionBuilds a disambiguated public tool name
extractSanitizedDomainFunctionExtracts and sanitizes domain from a URL
parseCliOptionsFunctionParses CLI arguments
CliOptionsTypeParsed CLI option shape
Message schema types and Zod schemas for the browser-relay protocol are also exported: BrowserToRelayMessageSchema, RelayToBrowserMessageSchema, RelayClientToServerMessageSchema, RelayServerToClientMessageSchema, ServerHelloMessageSchema, and their corresponding TypeScript types.

​
Troubleshooting

ProblemFix
No sources connectedVerify the page loaded embed.js and the relay process is running
No tools listedVerify tools are registered on the page’s WebMCP runtime. Confirm the runtime emits tool-change notifications (toolschanged or registerToolsChangedCallback)
Tool not foundTab reloaded or disconnected. Call webmcp_list_tools to refresh
Connection blockedVerify --widget-origin matches the host page origin and the relay port matches data-relay-port