webpage-mcp

webpage-mcp is the Node.js MCP server package used by the Webpage MCP project.

It provides:

• webpage-mcp: CLI for registration, diagnostics, and maintenance
• webpage-mcp-stdio: MCP stdio server entry used by MCP clients

This package uses:

• MCP Client <-> MCP Server: stdio
• Webpage MCP Connector (Chrome extension) <-> MCP Server: Chrome Native Messaging
• Internal bridge: local IPC socket / pipe

No localhost HTTP server or port is required.

Requirements

• Node.js >= 20
• Chrome/Chromium with the Webpage MCP Connector extension installed

Quick Start (npm users)

1. Install the Webpage MCP Connector Chrome extension (release zip or unpacked build).
2. Configure MCP client:

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

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

webpage-mcp-stdio will silently bootstrap Native Messaging on startup (manifest/runtime check + user-level auto-register when needed).

4. If connection still fails, run fallback recovery:

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

Recommended: copy the register command from extension popup/welcome page, because it already includes the current extension ID.

Version Compatibility

The Webpage MCP Connector Chrome extension and this webpage-mcp npm package are built and released from the same CI pipeline, but Chrome Web Store review and rollout timing is not fixed. This means the latest npm package may be available before the matching Chrome extension version reaches users.

We aim to keep nearby versions compatible. If you run into connection, protocol, or tool behavior issues, first make sure the Chrome extension and the MCP npm package use the same version for the best compatibility.

Is Register One-Time?

Usually yes. In many cases you do not need manual register because startup bootstrap handles it.

If manual register is used, re-register only when one of these changes:

• extension ID
• host install path
• Chrome profile/manifest files reset

Normal restarts (OS / Chrome / MCP client) do not require re-registering.

CLI Commands

webpage-mcp register [--browser chrome|chromium|all] [--detect] [--system] [--extension-id <id1,id2>] [--force]
webpage-mcp doctor [--fix] [--json] [--browser chrome|chromium|all]
webpage-mcp report [--json] [--output <file>] [--copy] [--no-redact] [--include-logs none|tail|full] [--log-lines <n>] [--browser chrome|chromium|all]
webpage-mcp fix-permissions

Notes:

• register --force is kept for compatibility; registration is idempotent.
• register --system requires admin/sudo privileges.
• report is intended for issue submission and troubleshooting.

Local Development (this monorepo)

Build package:

pnpm --filter webpage-mcp build

Verify local build health:

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

webpage-mcp-stdio started from local build also performs silent bootstrap. Only run manual register if connection still fails:

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

Use local stdio entry in MCP client config:

{
  "mcpServers": {
    "webpage-mcp-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/webpage-mcp/app/mcp-server/dist/mcp/mcp-server-stdio.js"
      ]
    }
  }
}

Environment Variables

• WEBPAGE_MCP_NATIVE_SOCKET
  • Explicit IPC socket/pipe path for both native host and stdio bridge.
• WEBPAGE_MCP_NATIVE_SOCKET_DIR
  • Unix only. Custom directory for default socket file.
• WEBPAGE_MCP_STDIO_CONNECT_TIMEOUT_MS
  • Max wait time (ms) for stdio bridge to connect to native socket.
• WEBPAGE_MCP_STDIO_CONNECT_RETRY_INTERVAL_MS
  • Retry interval (ms) for stdio bridge connection.
• WEBPAGE_MCP_EXTENSION_ID / WEBPAGE_MCP_EXTENSION_IDS
  • Override/add allowed extension IDs during registration.
• WEBPAGE_MCP_ALLOWED_ORIGINS
  • Additional allowed Chrome extension origins (comma or whitespace separated).
• WEBPAGE_MCP_AUTH_TOKEN
  • Optional token exposed to extension via auth_get_token (for UI display/copy and downstream use).

Optional Auth Token

Set an auth token if you want the extension to read it from the native host:

export WEBPAGE_MCP_AUTH_TOKEN="your-token"

Current behavior:

• Token is returned by native host auth_get_token.
• Token is not currently enforced as an auth check for MCP tool calls.

Troubleshooting

If you see ENOENT / "Unable to connect to native bridge socket":

1. Confirm extension is enabled and connected.
2. Check that the Chrome extension and webpage-mcp npm package versions match, especially after a fresh npm release.
3. Re-run registration with current extension ID:

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

4. Run:

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

5. Fully restart Chrome and retry.

Related Docs

• Root project guide: ../../README.md
• Troubleshooting: ../../docs/TROUBLESHOOTING.md