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

Comparison with Similar Projects

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:

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.

Build From Source (Developers)

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

# Install dependencies
pnpm install

# Build all packages
pnpm build

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

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

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

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)

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

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 — 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

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)

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

Tech Stack

Troubleshooting

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

CI/CD

License

MIT

Acknowledgements

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