webmcp-bridge lets a local MCP client call browser WebMCP tools through a stable local bridge.

Primary runtime path: local-mcp (stdio MCP) -> playwright -> browser navigator.modelContext

The bridge uses native WebMCP when available, and falls back to injected adapters when not:

• if the page exposes native WebMCP, calls go to browser navigator.modelContext
• if the page does not, the bridge falls back to an injected adapter path

This gives local MCP clients one call path for both:

• native WebMCP sites
• non-native sites that need a shim

Without a bridge, local MCP clients cannot directly use browser-only WebMCP capabilities such as:

• tools exposed by a live website in the current browser session
• tools that depend on existing site authentication
• human + AI collaboration on the same page

webmcp-bridge keeps execution in the browser where those capabilities already exist, while exposing a normal local stdio MCP surface to the caller.

• MCP client authors who need a stable local bridge to browser WebMCP
• browser app authors who want to expose native WebMCP tools
• adapter authors who want a fallback path for sites without native WebMCP yet

This project is intended for:

• WebMCP research and experimentation
• development, testing, and normal end-user workflows
• user-authorized actions inside the user's own browser session

It is not intended for:

• unauthorized data collection or bulk scraping
• bypassing access controls, rate limits, or platform restrictions
• abusive automation, account misuse, or privacy-invasive collection

Users are responsible for complying with applicable laws, website terms, and platform rules. If you use adapters or browser automation against a third-party service, you are responsible for that use and its consequences.

• connect a local MCP client to a native WebMCP website
• inject a fallback adapter for sites that do not expose WebMCP yet
• reuse the same logged-in browser session instead of moving credentials into the local process
• run headless automation or open a visible browser window for human + AI collaboration

• --url <https://site>: the site already exposes native WebMCP
• --site <name>: use a built-in fallback adapter such as x
• --adapter-module <specifier>: use a third-party adapter package

If your agent workflow uses skills, install the uxc skill first, then install the bridge skills.

Install from ClawHub:

clawhub install uxc
clawhub install webmcp-bridge
clawhub install board-webmcp
clawhub install x-webmcp
clawhub install google-webmcp
clawhub install webmcp-adapter-creator

Or install directly from GitHub:

npx -y skills@latest add holon-run/uxc --skill uxc
npx -y skills@latest add holon-run/webmcp-bridge --skill webmcp-bridge --skill board-webmcp --skill x-webmcp --skill google-webmcp --skill webmcp-adapter-creator

The GitHub form uses the shorter shorthand supported by skills add and installs only the named skills instead of referencing each SKILL.md URL directly. The commands do not pin --agent, so you can choose the target agent during installation.

The bridge skills depend on uxc because they create and use stable uxc link commands such as:

• board-webmcp-cli
• x-webmcp-cli
• google-webmcp-cli

Recommended skill flow:

1. Use webmcp-bridge for general site connection and link creation.
2. Use board-webmcp for the public board demo at https://board.holon.run.
3. Use webmcp-adapter-creator when a site has no native WebMCP and no existing adapter.

If your main workflow is "agent operates the site for me", install the skills in Agent skills first.

If you prefer direct CLI use instead of agent + skill use, start here:

Run directly from npm against the public native WebMCP demo:

npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless

When --browser-url is not used, local-mcp now defaults to a stable managed profile under ~/.uxc/webmcp-profile/<site-or-host> even if --user-data-dir is omitted.

To open a visible browser window for collaboration:

npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless

With uxc, create stable shortcuts:

uxc link board-webmcp-cli \
  "npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless --user-data-dir ~/.uxc/webmcp-profile/board" \
  --daemon-exclusive ~/.uxc/webmcp-profile/board

uxc link board-webmcp-ui \
  "npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless --user-data-dir ~/.uxc/webmcp-profile/board" \
  --daemon-exclusive ~/.uxc/webmcp-profile/board \
  --daemon-idle-ttl 0

The cli and ui links above are intended to reuse the same site profile through the same daemon/session, not through two independent browser processes at the same time. If a target site is sensitive to headed/headless switching or browser fingerprint changes, keep separate profiles for the two modes.

--headless and --no-headless set the preferred runtime presentation mode for bridge-managed sessions. The actual runtime mode is reported by bridge.session.status and may differ when local-mcp reattaches to an existing session.

Then:

board-webmcp-ui bridge.open
board-webmcp-ui diagram.get

Expected result:

• board-webmcp-ui bridge.open opens a visible browser session for the board demo
• board-webmcp-ui diagram.get returns the current board state as JSON

On a fresh machine, or when running under a brand new HOME, install Playwright browsers first:

npx playwright install

Or install globally:

npm i -g @webmcp-bridge/local-mcp
webmcp-local-mcp --url https://board.holon.run --headless

Run from this repository:

pnpm install
pnpm --filter @webmcp-bridge/local-mcp build
node packages/local-mcp/dist/cli.js --url https://board.holon.run --headless

Built-in fallback adapter mode:

webmcp-local-mcp --site x --headless --user-data-dir ~/.uxc/webmcp-profile/x

For auth-sensitive sites such as x, google, and weibo, the recommended first step is a headed session with a managed profile so local-mcp can bootstrap a normal browser for manual sign-in:

webmcp-local-mcp --site x --no-headless --user-data-dir ~/.uxc/webmcp-profile/x

Weibo example:

webmcp-local-mcp --site weibo --no-headless --user-data-dir ~/.uxc/webmcp-profile/weibo

Deterministic fixture mode:

webmcp-local-mcp --site fixture --headless

External adapter module mode:

webmcp-local-mcp --adapter-module @your-scope/webmcp-adapter --headless

webmcp-local-mcp owns one site session per process, drives a Playwright page, and proxies tools/list / tools/call into browser-side WebMCP execution.

The bridge uses native WebMCP when available, and falls back to injected adapters when not:

• native sites execute through browser navigator.modelContext
• non-native sites execute through injected WebMCP shim paths

Both paths return standard JSON-serializable MCP payloads to the local caller.

If a page exposes neither native WebMCP nor a configured adapter, local-mcp starts in overlay-bootstrap mode instead of failing immediately. In that mode:

• bridge.debug.eval can inspect or prototype page-context scripts
• bridge.overlay.* can persist draft overlay tools, switch them between namespaced and override, and export adapter drafts
• installed overlay tools always appear as overlay.<id>.<tool>
• overlays in override mode also expose their canonical tool names while preserving the overlay.<id>.* aliases

The public demo at https://board.holon.run is the easiest way to see human + AI collaboration on the same WebMCP surface.

• open a visible session with board-webmcp-ui bridge.open
• keep AI tool calls on board-webmcp-ui while the human is collaborating in the same visible session
• keep the browser open while the human and the AI work on the same diagram
• if the human closes the last headed window, that owner session ends; the next board-webmcp-ui bridge.open starts a new headed session on the same profile

See examples/board/README.md for the full collaboration flow in Codex / Claude Code.

• @webmcp-bridge/core: shared bridge contracts and shim runtime.
• @webmcp-bridge/playwright: WebMCP page gateway for Playwright.
• @webmcp-bridge/adapter-x: production fallback adapter for X/Twitter.
• @webmcp-bridge/adapter-weibo: fallback adapter for Weibo reads, writes, article workflows, and search.
• @webmcp-bridge/adapter-fixture: deterministic fallback adapter for integration/contract tests.
• @webmcp-bridge/testkit: shared contract test helpers.
• @webmcp-bridge/local-mcp: local stdio MCP server.

This repository includes six agent skills with distinct responsibilities:

• webmcp-bridge: general bridge operations for existing sites. Use it to decide between --url, --site, and --adapter-module, create fixed uxc links, manage per-site profiles, and switch between headless and UI bridge modes.
• board-webmcp: site wrapper for the public native demo at https://board.holon.run. Use it when the task is specifically about the shared board example.
• x-webmcp: site wrapper for X, including timeline, Grok, and X Articles workflows.
• google-webmcp: site wrapper for Google and Gemini workflows, including text and image generation.
• weibo-webmcp: site wrapper for Weibo timeline, post, comment, article, and search workflows.
• webmcp-adapter-creator: adapter creation workflow for sites that do not expose native WebMCP. Use it to scaffold a new adapter package, design tool schemas, and implement browser-side request-template execution.

These skills assume the uxc CLI and the uxc skill are already installed.

They are published on ClawHub as webmcp-bridge, board-webmcp, x-webmcp, google-webmcp, and webmcp-adapter-creator.

See Adapter Authoring for:

• manifest + createAdapter module contract
• tool naming and schema guidelines
• pagination/error shape conventions
• fail-closed adapter requirements

examples/board is a native WebMCP provider example built as a browser app, not an adapter.

Public demo:

webmcp-local-mcp --url https://board.holon.run --headless

Run it locally:

pnpm --filter @webmcp-bridge/example-board dev

Then connect through the existing bridge:

webmcp-local-mcp --url http://127.0.0.1:4173 --headless

This example is meant to demonstrate human + AI collaboration on the same diagram surface.

Useful board tools:

• bridge.open / bridge.close
• diagram.get / diagram.loadDemo / diagram.setTitle / diagram.export
• nodes.*
• edges.*
• selection.get / selection.remove
• view.fit

pnpm typecheck
pnpm test
pnpm lint
pnpm build

Releases are published from GitHub Actions through Changesets plus npm trusted publishing. Do not publish from a local shell.

pnpm changeset

After the feature PR with its changeset lands on main, the Release workflow opens or updates a version PR. Merging that version PR publishes the packages from GitHub Actions with npm provenance. For release details, see docs/release.md.

To validate the monorepo locally before merging:

pnpm typecheck
pnpm test
pnpm lint
pnpm build

• Assumes users are already authenticated in the browser session.
• Does not implement credential vaulting or auth bypass.
• Target URL defaults to adapter manifest and can be overridden by CLI, but must match adapter host allowlist.