Webpage MCP

How It Works

┌──────────┐     MCP stdio    ┌───────────────┐
│ AI Client├─────────────────►│   MCP Server  │
└──────────┘                  └───────┬───────┘
       Native Messaging stdin/stdout  │
                                      │
┌─────────────┐  Chrome APIs ┌────────▼───────┐
│ Your Webpage│◄─────────────┤  MCP Connector │
└─────────────┘   DevTools   └────────────────┘

The Webpage MCP Connector (Chrome extension) exposes real browser capabilities as MCP tools. The MCP Server bridges AI clients and the connector using Chrome Native Messaging. MCP clients connect over stdio only (no localhost HTTP transport).

Webpage MCP is best understood as a browser-native workflow layer for Chrome, not just a page-control bridge. Recent Chrome releases have made Chrome DevTools MCP capable of connecting to active browser sessions, which makes protocol-level control of existing tabs much easier. Webpage MCP complements that model by focusing on what DevTools MCP does not try to be: Chrome extension APIs, saved workflows, in-browser operator UI, semantic cross-tab memory, and page-to-code editing flows.

Related MCP server: Chrome MCP Server

Core Features

Comparison with Similar Projects

Playwright-based MCP Servers

Chrome DevTools MCP

Chrome DevTools MCP is an excellent choice when your primary goal is protocol-level debugging of an already-open browser session. Webpage MCP is most valuable one layer above that: browser-native workflows, persistent local automation, and Chrome extension APIs that CDP alone does not cover well.

Best Used Together

A strong local setup is to use Chrome DevTools MCP as the debugging engine and Webpage MCP as the browser-native workflow layer. DevTools MCP can own deep protocol inspection, while Webpage MCP owns browser-native APIs, saved automations, in-browser UI, and page-to-code workflows.

Installation

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>

2. Run one-shot auto-fix:

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

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

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

Version Compatibility

The Chrome extension and the 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.

Build From Source (Developers)

1. Clone and Build

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

# Install dependencies
pnpm install

# 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:

# From repo root, use the built local CLI entry
node app/mcp-server/dist/cli.js register --detect

# 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

# Diagnose installation issues
node app/mcp-server/dist/cli.js doctor

# Generate a full diagnostic report
node app/mcp-server/dist/cli.js report

Open Chrome and click the extension icon — it should show a connected status.

Configuration

Connecting AI Clients

Use stdio transport via npx:

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

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.

Local Absolute Path (Dev)

For local development, you can point MCP directly to the built stdio entry:

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

Important:

• This stdio process still depends on the native bridge socket created by the Chrome Native host.

• Keep Chrome open and ensure the extension is connected to native host.

• Default bridge socket path (macOS/Linux): ~/.webpage-mcp/native-<uid>.sock.

• If you customized WEBPAGE_MCP_NATIVE_SOCKET, both processes must use the same value.

Notes

• The current architecture is fully native/stdio and does not expose localhost MCP/agent HTTP endpoints.

• Multiple instances are identified by instanceId; data transport is native/stdio only.

• For npx usage, keep -p webpage-mcp@latest in args so webpage-mcp-stdio resolves as the executed bin.

MCP Browser Tools

Additional Capabilities

• AI Agent Chat Sidepanel — Built-in sidepanel for chatting with AI agents (Claude Code CLI, OpenAI Codex CLI) directly from Chrome, with project management, session history, and streaming output

• Record, Replay, and Publish — Record browser actions, replay them as automated flows, publish reusable flows, and expose them as dynamic MCP tools (flow.<slug>)

• Triggerable Browser Workflows — Launch flows from URL matches, DOM appearance, intervals, one-time schedules, keyboard commands, and context-menu actions

• Web Editor — Visual in-page DOM editor overlay with a property panel, transaction system, undo/redo, and structured apply-to-code handoff (Cmd+Shift+E)

• Quick Panel — Keyboard-triggered floating AI chat accessible from any page, with page context and streaming responses (Cmd+Shift+U)

• Semantic Search — On-device embedding model (all-MiniLM-L6-v2) with HNSW vector index for searching tab content across live browser state

• Element Marker — Annotate DOM elements with stable names/selectors so agents and workflows can refer to page targets more reliably

Development

Quick Start

# Install dependencies
pnpm install

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

Individual Package Commands

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

# MCP server
pnpm dev:mcp              # Dev mode with auto-reload
pnpm build:mcp            # Production build

# Shared library
pnpm dev:shared           # Watch mode
pnpm build:shared         # Production build

# WASM SIMD (requires Rust toolchain)
pnpm build:wasm           # Build and copy to extension

Testing

# Chrome extension tests (Vitest)
cd app/chrome-extension && pnpm test

# MCP server tests (Jest)
cd app/mcp-server && pnpm test

Linting & Formatting

pnpm lint          # Run ESLint across all packages
pnpm lint:fix      # Auto-fix lint issues
pnpm format        # Format with Prettier
pnpm typecheck     # TypeScript type checking

CLI Reference

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)

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.

Tech Stack

Troubleshooting

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

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"])

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

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

CI/CD

ci.yml

• Trigger: pushes and pull requests on main/develop

• Runs: install, lint, typecheck (mcp/shared + extension), tests, build

release.yml

• Trigger: tag push v* and manual dispatch

• Builds release assets:

  • Chrome extension zip (app/chrome-extension/.output/webpage-mcp-connector-<version>-chrome-extension.zip)

  • MCP server npm tarball (.tgz)

  • SHA256SUMS.txt

• On tag pushes, creates a GitHub Release and uploads assets

• On tag pushes (v*), publishes webpage-mcp to npm (requires NPM_AUTH_TOKEN secret)

• Manual npm publish available via workflow_dispatch with publish_npm=true

Acknowledgements

This project is based on hangwin/mcp-chrome. Special thanks to the original author and all contributors for their foundational work.

License

MIT