webpage-mcp (MCP Server Package)

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.

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. Re-run registration with current extension ID:

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

3. Run:

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

4. Fully restart Chrome and retry.

Related Docs

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