https://github.com/mcpland/webpage-mcp
Turn your existing webpages into an MCP server for agent control
https://github.com/mcpland/webpage-mcp
ai-agent browser-agent browser-automation mcp mcp-server
Last synced: 4 months ago
JSON representation
Turn your existing webpages into an MCP server for agent control
- Host: GitHub
- URL: https://github.com/mcpland/webpage-mcp
- Owner: mcpland
- License: mit
- Created: 2026-02-24T15:43:48.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-13T16:13:37.000Z (4 months ago)
- Last Synced: 2026-04-13T18:05:24.287Z (4 months ago)
- Topics: ai-agent, browser-agent, browser-automation, mcp, mcp-server
- Language: TypeScript
- Homepage:
- Size: 23.1 MB
- Stars: 10
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://developer.chrome.com/docs/extensions/develop/concepts/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](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session), 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.
## Core Features
| | Feature | Description |
| ----------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| :grinning: | **Chatbot/Model Agnostic** | Let any LLM, chatbot client, or agent automate your browser |
| :star: | **Use Your Original Browser** | Seamlessly integrate with your existing browser environment (configs, login states, etc.) |
| :computer: | **Fully Local** | Pure local MCP server ensuring user privacy |
| :electric_plug: | **Native Stdio Transport** | Native Messaging + stdio only (no localhost HTTP port) |
| :racing_car: | **Cross-Tab** | Cross-tab context support |
| :control_knobs: | **Workflow Runtime** | Record, publish, trigger, and replay flows; expose saved browser workflows as MCP tools |
| :speech_balloon: | **In-Browser Agent UX** | Built-in sidepanel, Quick Panel, element picker, and workflow views keep the agent inside Chrome |
| :building_construction: | **Apply-to-Code Web Editor** | Visual in-page editing with transactions, undo/redo, and structured apply payloads for coding agents |
| :brain: | **Semantic Search** | Built-in vector database for intelligent browser tab content discovery |
| :mag: | **Smart Content Analysis** | AI-powered text extraction and similarity matching |
| :globe_with_meridians: | **20+ Tools** | Screenshots, network monitoring, interactive operations, bookmark management, browsing history, and more |
| :rocket: | **SIMD-Accelerated AI** | Custom WebAssembly SIMD optimization for 4-8x faster vector operations |
## Comparison with Similar Projects
### Playwright-based MCP Servers
| Dimension | Playwright-based MCP Server | Webpage MCP Connector + MCP Server |
| ---------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **First-time Setup** | :white_check_mark: Usually simpler: install & run | :white_check_mark: Usually install + configure; manual register is fallback |
| **Bootstrap / Self-healing** | :warning: Failures often require manual environment fixes | :white_check_mark: Startup silent bootstrap (manifest/runtime check + auto user-level register) |
| **Resource Usage** | :x: Launches a separate automation browser | :white_check_mark: Reuses the user's already-open Chrome |
| **User Session Reuse** | :x: Often requires separate login/state management | :white_check_mark: Reuses existing profile session/cookies |
| **Real-user Environment** | :warning: Automation-oriented environment | :white_check_mark: Real user profile, settings, extensions, tabs |
| **API Access Surface** | :warning: Constrained by Playwright API boundaries | :white_check_mark: Chrome extension platform + native APIs |
| **CI / Headless Fit** | :white_check_mark: Strong fit for CI and headless workflows | :warning: Better suited for local interactive workflows |
| **Determinism** | :white_check_mark: Stronger reproducibility in controlled runs | :warning: Affected by live user environment/state |
| **Startup Latency** | :x: Needs browser automation bootstrap | :white_check_mark: Mainly extension/native bridge activation |
| **Request Overhead** | :warning: Extra orchestration adds overhead | :white_check_mark: Lower overhead in long-lived local sessions |
| **Post-setup Reliability** | :warning: More moving parts can increase failure surface | :white_check_mark: One-time registration; stable across restarts |
### 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.
| Dimension | Chrome DevTools MCP | Webpage MCP Connector + MCP Server |
| ---------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Primary Strength** | DevTools- and CDP-centric debugging, inspection, tracing, and performance analysis | Browser-native workflow automation, operator UX, and persistent local browser tooling |
| **Existing Browser Session** | :white_check_mark: Strong fit for active browser sessions | :white_check_mark: Strong fit for the user's real Chrome profile and tabs |
| **Chrome-Native APIs** | :warning: Mostly limited to DevTools / CDP surfaces | :white_check_mark: Extension APIs such as bookmarks, history, sidepanel, context menus, alarms, and more |
| **Saved Workflows** | :warning: Not the main product surface | :white_check_mark: Built-in record/replay, publishing, dynamic tools, and reusable flow variables |
| **Triggers and Scheduling** | :warning: Typically external orchestration | :white_check_mark: Built-in manual, URL, DOM, interval, once, command, and context-menu triggers |
| **In-Browser UX** | :warning: Usually operated from an external agent or CLI | :white_check_mark: Built-in sidepanel, Quick Panel, workflow views, and page-level pickers |
| **Cross-Tab Memory** | :warning: Not a built-in focus | :white_check_mark: Built-in semantic indexing and search across live tabs |
| **Visual Editing** | :warning: Not a built-in focus | :white_check_mark: Web Editor with transactions, undo/redo, and apply-to-code payloads |
| **Best Fit** | Debugging pages, network, console, performance, and memory | Turning Chrome into a persistent local automation workspace for agents and human operators |
### 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](https://chromewebstore.google.com/detail/webpage-mcp-connector/iehgbogeakiedihodennfcnigojnncag?hl=en).
**2.** Add `webpage-mcp` to your MCP client config:
```json
{
"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:
```bash
npx -y webpage-mcp@latest register --browser chrome --force --extension-id
```
2. Run one-shot auto-fix:
```bash
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.
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
```bash
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:
```bash
# 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
```
This writes/updates the JSON manifest in Chrome's `NativeMessagingHosts/` directory so Chrome can launch the MCP server process.
#### 5. Verify Installation
```bash
# 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`:
```json
{
"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:
```json
{
"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-.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 the current tab or open a URL in a new tab/window; also supports refresh/history |
| `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, and Publish** — Record browser actions, replay them as automated flows, publish reusable flows, and expose them as dynamic MCP tools (`flow.`)
- **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+O`)
- **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](https://huggingface.co/sentence-transformers/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
```bash
# Install dependencies
pnpm install
# Start all packages in dev mode (shared builds first, then parallel)
pnpm dev
```
### Individual Package Commands
```bash
# 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
```bash
# Chrome extension tests (Vitest)
cd app/chrome-extension && pnpm test
# MCP server tests (Jest)
cd app/mcp-server && pnpm test
```
### Linting & Formatting
```bash
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
```bash
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 Target browser: chrome, chromium, or all
-d, --detect Auto-detect installed browsers
-e, --extension-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:
```bash
npx -y webpage-mcp@latest register --browser chrome --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](https://wxt.dev/) (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
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. Prefer the exact register command generated in extension popup/welcome and run it once
4. Fully restart Chrome (quit all Chrome processes), then click Connect again
MCP client can't reach the server
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"]`)
Tools return errors or time out
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
Generate a diagnostic report
```bash
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--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](https://github.com/hangwin/mcp-chrome). Special thanks to the original author and all contributors for their foundational work.