Install dependencies

pnpm install

Install dependencies

pnpm install

WASM SIMD (requires Rust toolchain)

pnpm build:wasm # Build and copy to extension ```

Installation

Build From Source (Developers)

<details> <summary><strong>Click to expand</strong></summary>

1. Clone and Build

```bash git clone https://github.com/mcpland/webpage-mcp.git cd webpage-mcp

Build all packages

pnpm build

#### 2. Install the Chrome Extension

1. Open Chrome and navigate to `chrome://extensions/`
2. Enable **Developer mode** (toggle in top right)
3. Click **Load unpacked**
4. Select the `app/chrome-extension/.output/chrome-mv3` folder

> This repository does not currently commit binary release zip files. To generate one locally, run `pnpm --filter webpage-mcp-connector zip` and use the artifact from `app/chrome-extension/.output/`.

#### 3. Start MCP Client First

Use the local stdio entry in your MCP client config (example below). On startup, `mcp-server-stdio` will attempt silent bootstrap (manifest/runtime check + user-level auto-register).

#### 4. Fallback: Manual Register (Only If Needed)

If the extension still cannot connect, run:

Diagnose installation issues

node app/mcp-server/dist/cli.js doctor

Start all packages in dev mode (shared builds first, then parallel)

pnpm dev ```

Quick Start

1. Install the Webpage MCP Connector Chrome extension first in chrome web store. https://chromewebstore.google.com/detail/webpage-mcp-connector/iehgbogeakiedihodennfcnigojnncag?hl=en.

2. Add webpage-mcp to your MCP client config:

{
  "mcpServers": {
    "webpage-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"]
    }
  }
}

3. Start your MCP client (with Chrome open and extension enabled).

webpage-mcp-stdio now performs silent bootstrap on startup: it checks Native Messaging manifest/runtime and auto-registers user-level host when needed.

4. If extension still cannot connect, use fallback recovery:

1. Open extension welcome.html or popup and copy the register command (already includes current extension ID), then run it:

npx -y webpage-mcp@latest register --browser chrome --force --extension-id <extension_id_from_popup_or_welcome>

1. Run one-shot auto-fix:

npx -y webpage-mcp@latest doctor --fix

1. Use the extension popup status refresh button once to reconnect and sync status, then restart MCP client.

<details> <summary><strong>When do I need to re-register?</strong></summary>

For most users, manual registration is not required because startup bootstrap handles it automatically.

If you did run manual registration, it is typically one-time per machine/profile. You do not need to re-run it for normal restarts (OS/Chrome/MCP client). Re-run only when:

• Extension ID changes
• Manifest path changes
• Installation path changes
• Chrome profile data is reset

</details>

Quick Start

```bash

Configuration

Claude Desktop Configuration

Add to your Claude Desktop MCP config (claude_desktop_config.json) — use the same npx stdio config above.

Codex Configuration

Codex stores MCP configuration in ~/.codex/config.toml by default. You can also use a project-local .codex/config.toml when the server should only be enabled for one repository.

Add webpage-mcp with a [mcp_servers.<server-name>] TOML table:

[mcp_servers."webpage-mcp"]
command = "npx"
args = ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"]

command is required. args is optional and should be an array when used.

You can also add it with Codex CLI:

codex mcp add webpage-mcp -- npx -y -p webpage-mcp@latest webpage-mcp-stdio

After adding the server, restart Codex if needed and use /mcp in the Codex TUI to confirm webpage-mcp is enabled.

Register Options

npx -y webpage-mcp@latest register [options]

Options:
  -f, --force              Compatibility flag (accepted; registration is currently idempotent)
  -s, --system             System-level install (requires sudo/admin)
  -b, --browser <browser>  Target browser: chrome, chromium, or all
  -d, --detect             Auto-detect installed browsers
  -e, --extension-id <id>  Override extension ID(s) for allowed_origins (comma-separated)

<details> <summary><strong>Additional registration details</strong></summary>

When --browser chrome is used, the installer also writes channel-compatible manifests on macOS/Linux (for example Chrome Stable/Beta/Canary/Chrome for Testing paths) to reduce "native host not found" channel mismatch issues. The installer also attempts to discover local unpacked Webpage MCP Connector extension IDs from browser profiles and add them to allowed_origins.

For unpacked extensions with a custom ID, you can re-register with:

npx -y webpage-mcp@latest register --browser chrome --extension-id <your_extension_id>

The extension popup and welcome page can generate this command automatically using chrome.runtime.id, which avoids manual ID lookup mistakes. The generated command may include --force; this flag is optional.

</details>

---

From repo root, use the built local CLI entry

node app/mcp-server/dist/cli.js register --detect

CLI Reference

Or specify browser/extension id explicitly

node app/mcp-server/dist/cli.js register --browser chrome --extension-id <your_extension_id>

This writes/updates the JSON manifest in Chrome's `NativeMessagingHosts/` directory so Chrome can launch the MCP server process.

#### 5. Verify Installation

Individual Package Commands

```bash

Chrome extension

pnpm dev:extension # Dev mode with HMR pnpm build:extension # Production build

Chrome extension tests (Vitest)

cd app/chrome-extension && pnpm test

Comparison with Similar Projects

Troubleshooting

<details> <summary><strong>Extension fails to connect</strong></summary>

1. Ensure the native host is registered: npx -y webpage-mcp@latest doctor
2. Check that Node.js >= 20 is available at the registered path
3. Check that the Chrome extension and webpage-mcp npm package versions match, especially after a fresh npm release
4. Prefer the exact register command generated in extension popup/welcome and run it once
5. Fully restart Chrome (quit all Chrome processes), then click Connect again

</details>

<details> <summary><strong>MCP client can't reach the server</strong></summary>

1. Ensure Chrome is open and the extension is enabled
2. Ensure native host is connected (npx -y webpage-mcp@latest doctor)
3. Use npx stdio config in your MCP client (command: "npx", args: ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"])

</details>

<details> <summary><strong>Tools return errors or time out</strong></summary>

1. Make sure Chrome is open with the extension enabled
2. Check the extension's service worker console for errors (chrome://extensions/ > Inspect views)
3. Some tools (e.g., chrome_network_capture) require specific page states

</details>

<details> <summary><strong>Generate a diagnostic report</strong></summary>

npx -y webpage-mcp@latest report --copy    # Copies to clipboard
npx -y webpage-mcp@latest doctor --fix     # Auto-fix common issues

</details>

---