Webpage MCP

Turn your webpage into a fully-featured MCP server

Let AI assistants like Claude, Cursor, Windsurf, and other MCP-compatible clients control your webpage — navigate pages, take screenshots, click elements, read content, capture network traffic, run JavaScript, and much more.

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).

Core Features

	Feature	Description
😀	Chatbot/Model Agnostic	Let any LLM, chatbot client, or agent automate your browser
⭐	Use Your Original Browser	Seamlessly integrate with your existing browser environment (configs, login states, etc.)
💻	Fully Local	Pure local MCP server ensuring user privacy
🔌	Native Stdio Transport	Native Messaging + stdio only (no localhost HTTP port)
🏎️	Cross-Tab	Cross-tab context support
🧠	Semantic Search	Built-in vector database for intelligent browser tab content discovery
🔍	Smart Content Analysis	AI-powered text extraction and similarity matching
🌐	20+ Tools	Screenshots, network monitoring, interactive operations, bookmark management, browsing history, and more
🚀	SIMD-Accelerated AI	Custom WebAssembly SIMD optimization for 4-8x faster vector operations

Comparison with Similar Projects

Dimension	Playwright-based MCP Server	Webpage MCP Connector + MCP Server
First-time Setup	✅ Usually simpler: install & run	✅ Usually install + configure; manual register is fallback
Bootstrap / Self-healing	⚠️ Failures often require manual environment fixes	✅ Startup silent bootstrap (manifest/runtime check + auto user-level register)
Resource Usage	❌ Launches a separate automation browser	✅ Reuses the user's already-open Chrome
User Session Reuse	❌ Often requires separate login/state management	✅ Reuses existing profile session/cookies
Real-user Environment	⚠️ Automation-oriented environment	✅ Real user profile, settings, extensions, tabs
API Access Surface	⚠️ Constrained by Playwright API boundaries	✅ Chrome extension platform + native APIs
CI / Headless Fit	✅ Strong fit for CI and headless workflows	⚠️ Better suited for local interactive workflows
Determinism	✅ Stronger reproducibility in controlled runs	⚠️ Affected by live user environment/state
Startup Latency	❌ Needs browser automation bootstrap	✅ Mainly extension/native bridge activation
Request Overhead	⚠️ Extra orchestration adds overhead	✅ Lower overhead in long-lived local sessions
Post-setup Reliability	⚠️ More moving parts can increase failure surface	✅ One-time registration; stable across restarts

Installation

Quick Start

1. Install the Webpage MCP Connector Chrome extension first (store package or unpacked build). https://github.com/mcpland/webpage-mcp/releases

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:

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>

Run one-shot auto-fix:

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

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

When do I need to re-register?

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

Build From Source (Developers)

Click to expand

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

Open Chrome and navigate to chrome://extensions/
Enable Developer mode (toggle in top right)
Click Load unpacked
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.

Local Absolute Path (Dev)

Click to expand

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

Tool	Description
`get_windows_and_tabs`	Get all open browser windows and tabs
`chrome_navigate`	Navigate to a URL, refresh, or navigate history (back/forward)
`chrome_screenshot`	Take a screenshot of the page or a specific element
`chrome_read_page`	Get an accessibility tree of visible elements on the page
`chrome_computer`	Mouse and keyboard interaction with the browser (computer use)
`chrome_click_element`	Click elements via CSS selector, XPath, element ref, or coordinates
`chrome_fill_or_select`	Fill or select form elements (input, textarea, select, checkbox, radio)
`chrome_keyboard`	Simulate keyboard input (keys, combinations, or text)
`chrome_javascript`	Execute JavaScript code in a browser tab
`chrome_get_web_content`	Fetch and parse web page content
`chrome_network_request`	Send network requests from the browser context (with cookies)
`chrome_network_capture`	Capture network requests (start/stop, optional response bodies via CDP)
`chrome_console`	Capture console output (snapshot or persistent buffer mode)
`chrome_history`	Search and retrieve browsing history
`chrome_bookmark_search`	Search bookmarks by title and URL
`chrome_bookmark_add`	Add a new bookmark
`chrome_bookmark_delete`	Delete a bookmark
`chrome_switch_tab`	Switch to a specific tab
`chrome_close_tabs`	Close one or more tabs
`chrome_upload_file`	Upload files to web forms via CDP
`chrome_handle_dialog`	Handle JavaScript dialogs (alert/confirm/prompt)
`chrome_handle_download`	Wait for and retrieve download details
`chrome_request_element_selection`	Let the user manually select elements on the page
`chrome_gif_recorder`	Record browser activity as an animated GIF
`performance_start_trace`	Start a performance trace recording
`performance_stop_trace`	Stop the active performance trace
`performance_analyze_insight`	Get a lightweight summary of the last recorded trace

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 — Record browser actions and replay them as automated flows; published flows are exposed as dynamic MCP tools (flow.<slug>)
Web Editor — Visual in-page DOM editor overlay with property panel and transaction system (Cmd+Shift+O)
Quick Panel — Keyboard-triggered floating AI chat accessible from any page (Cmd+Shift+U)
Semantic Search — On-device embedding model (all-MiniLM-L6-v2) with HNSW vector index for searching tab content
Element Marker — Annotate DOM elements with names/selectors, accessible to AI tools via context menu

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

Command	Description
`register`	Register the Native Messaging host manifest
`fix-permissions`	Fix execution permissions for native host files
`doctor`	Diagnose installation and environment issues
`report`	Export a diagnostic report for troubleshooting

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)

Additional registration details

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

Layer	Technology
Extension framework	WXT (Vite-based)
Extension UI	React 18 + TailwindCSS v4
Flow builder	@xyflow/react (ReactFlow)
MCP server	Node.js Native Messaging + local IPC
MCP SDK	@modelcontextprotocol/sdk
Agent SDK	@anthropic-ai/claude-agent-sdk
Database	SQLite (better-sqlite3 + drizzle-orm)
Semantic search	@xenova/transformers (ONNX) + hnswlib-wasm
SIMD math	Rust/WASM (wasm-bindgen + wide)
GIF recording	gifenc
Testing	Vitest
Package manager	pnpm workspaces

Troubleshooting

Extension fails to connect

Ensure the native host is registered: npx -y webpage-mcp@latest doctor
Check that Node.js >= 20 is available at the registered path
Prefer the exact register command generated in extension popup/welcome and run it once
Fully restart Chrome (quit all Chrome processes), then click Connect again

MCP client can't reach the server

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

Tools return errors or time out

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

Generate a diagnostic report

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

CI/CD

GitHub Actions workflows

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

License

MIT

Acknowledgements

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

Name		Name	Last commit message	Last commit date
Latest commit History 248 Commits
.github/workflows		.github/workflows
app		app
docs		docs
packages		packages
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
commitlint.config.cjs		commitlint.config.cjs
eslint.config.js		eslint.config.js
logo.png		logo.png
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

Webpage MCP

How It Works

Core Features

Comparison with Similar Projects

Installation

Quick Start

Build From Source (Developers)

1. Clone and Build

2. Install the Chrome Extension

3. Start MCP Client First

4. Fallback: Manual Register (Only If Needed)

5. Verify Installation

Configuration

Connecting AI Clients

Claude Desktop Configuration

Local Absolute Path (Dev)

Notes

MCP Browser Tools

Additional Capabilities

Development

Quick Start

Individual Package Commands

Testing

Linting & Formatting

CLI Reference

Register Options

Tech Stack

Troubleshooting

CI/CD

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages