Webpage MCP

Webpage MCP

Turn your webpage into a fully-featured MCP server

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

______________________________________________________________________

运作原理

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

这 网页MCP连接器 （Chrome扩展程序）作为MCP工具公开了真正的浏览器功能。这 MCP服务器 使用Chrome桥接AI客户端和连接器 本地消息传递.MCP客户端仅通过stdio连接（没有本地主机HTTP传输）。

网页MCP最好被理解为Chrome的浏览器原生工作流层，而不仅仅是页面控制桥。最近的Chrome版本已经 Chrome DevTools MCP能够连接到活动的浏览器会话，这使得现有标签的协议级控制变得更加容易。网页MCP通过关注DevTools MCP不想成为的东西来补充这一模型：Chrome扩展API、保存的工作流、浏览器内操作员UI、语义交叉标签内存和页面到代码编辑流。

核心功能

与类似项目的比较

基于剧作家的MCP服务器

Chrome开发工具MCP

当您的主要目标是对已打开的浏览器会话进行协议级调试时，Chrome DevTools MCP是一个不错的选择。网页MCP是最有价值的一层：浏览器原生工作流、持久本地自动化和Chrome扩展API，而CDP本身并不能很好地覆盖这些。

最好一起使用

一个强大的本地设置是使用Chrome DevTools MCP作为调试引擎，使用网页MCP作为浏览器原生工作流层。DevTools MCP可以拥有深度协议检查，而网页MCP拥有浏览器原生API、保存的自动化、浏览器内UI和页面到代码工作流。

安装

快速开始

1. 安装 网页MCP连接器 Chrome扩展程序首次出现在Chrome网上商店。 https://chromewebstore.google.com/detail/webpage-mcp-connector/iehgbogeakiedihodennfcnigojnncag?hl=en.

2. 添加 webpage-mcp 到您的MCP客户端配置：

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

3. 启动您的MCP客户端（打开Chrome浏览器并启用扩展程序）。

webpage-mcp-stdio 现在在启动时执行静默引导：它检查本机消息清单/运行时，并在需要时自动注册用户级主机。

4. 如果扩展仍然无法连接，请使用回退恢复：

1. 打开扩展 welcome.html 或者弹出并复制注册命令（已包含当前扩展ID），然后运行它：

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

1. 运行一次自动修复：

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

1. 使用一次扩展弹出状态刷新按钮重新连接并同步状态，然后重新启动MCP客户端。

When do I need to re-register?

对于大多数用户来说，不需要手动注册，因为启动引导会自动处理。

如果您确实运行了手动注册，则通常是每台机器/配置文件一次。你做 不 需要重新运行它以进行正常重启（OS/Chrome/MCP客户端）。仅在以下情况下重新运行：

• 扩展ID更改
• 清单路径更改
• 安装路径更改
• Chrome配置文件数据已重置

版本兼容性

Chrome扩展程序和 webpage-mcp npm包是从同一个CI管道构建和发布的，但Chrome Web Store的审查和推出时间并不固定。这意味着在匹配的Chrome扩展程序版本到达用户之前，最新的npm包可能已经可用。

我们的目标是保持附近版本的兼容性。如果您遇到连接、协议或工具行为问题，请首先确保Chrome扩展程序和MCP npm包使用相同的版本以获得最佳兼容性。

从源代码构建（开发人员）

Click to expand

1.克隆和构建

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

# Install dependencies
pnpm install

# Build all packages
pnpm build

2.安装Chrome扩展程序

1. 打开Chrome浏览器并导航到 chrome://extensions/
2. 启用 开发者模式 （在右上角切换）
3. 点击 装载时未包装
4. 选择 app/chrome-extension/.output/chrome-mv3 文件夹

此存储库当前未提交二进制发布zip文件。要在本地生成一个，请运行 pnpm --filter webpage-mcp-connector zip 并使用来自的工件 app/chrome-extension/.output/.

3.先启动MCP客户端

在MCP客户端配置中使用本地stdio条目（如下示例）。在启动时， mcp-server-stdio 将尝试静默引导（清单/运行时检查+用户级自动注册）。

4.回退：手动注册（仅在需要时）

如果扩展仍然无法连接，请运行：

# 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 

这将写入/更新Chrome中的JSON清单 NativeMessagingHosts/ 目录，以便Chrome可以启动MCP服务器进程。

5.验证安装

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

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

打开Chrome浏览器并单击扩展程序图标——它应该显示连接状态。

______________________________________________________________________

配置

连接AI客户端

通过以下方式使用stdio传输 npx:

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

Claude桌面配置

添加到您的Claude Desktop MCP配置(claude_desktop_config.json)--使用相同的 npx 上面的stdio配置。

Codex配置

Codex将MCP配置存储在 ~/.codex/config.toml 默认情况下。您还可以使用本地项目 .codex/config.toml 当服务器只应为一个存储库启用时。

添加 webpage-mcp 带着一个 [mcp_servers.] TOML桌子：

[mcp_servers."webpage-mcp"]
command = "npx"
args = ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"]

command 是必需的。 args 是可选的，使用时应该是数组。

您还可以使用Codex CLI添加它：

codex mcp add webpage-mcp -- npx -y -p webpage-mcp@latest webpage-mcp-stdio

添加服务器后，如果需要，请重新启动Codex并使用 /mcp 在食品法典委员会TUI中确认 webpage-mcp 已启用。

本地绝对路径（Dev）

Click to expand

对于本地开发，您可以将MCP直接指向已构建的stdio条目：

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

重要提示：

• 此stdio进程仍然依赖于Chrome本机主机创建的本机网桥套接字。
• 保持Chrome打开，并确保扩展程序已连接到本机主机。
• 默认网桥套接字路径（macOS/Linux）： ~/.webpage-mcp/native-.sock.
• 如果你定制 WEBPAGE_MCP_NATIVE_SOCKET，两个进程必须使用相同的值。

备注

• 当前的架构是完全原生/stdio的，不公开localhost MCP/代理HTTP端点。
• 多个实例由以下方式标识 instanceId；数据传输仅限于原生/stdio。
• 对于 npx 使用，保持 -p webpage-mcp@latest 在args中，so webpage-mcp-stdio 解析为已执行的bin。

______________________________________________________________________

MCP浏览器工具

附加功能

• AI代理聊天侧面板 --内置侧面板，可直接从Chrome与AI代理（Claude Code CLI、OpenAI Codex CLI）聊天，具有项目管理、会话历史和流式输出功能
• 录制、回放和发布 --记录浏览器操作，将其作为自动化流回放，发布可重用流，并将其作为动态MCP工具公开(flow.)
• 可触发浏览器工作流 --从URL匹配、DOM外观、间隔、一次性计划、键盘命令和上下文菜单操作启动流
• Web编辑器 --可视化的页面内DOM编辑器覆盖，具有属性面板、事务系统、撤消/重做和结构化的应用到代码切换(Cmd+Shift+E)
• 快捷面板 --键盘触发的浮动AI聊天可从任何页面访问，具有页面上下文和流式响应(Cmd+Shift+U)
• 语义搜索 --设备嵌入模型(全迷你LM-L6-v2)使用HNSW矢量索引在实时浏览器状态中搜索标签内容
• 元素标记 --用稳定的名称/选择器注释DOM元素，以便代理和工作流可以更可靠地引用页面目标

______________________________________________________________________

发展

快速开始

# Install dependencies
pnpm install

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

单个包命令

# 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

测试

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

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

装订和格式化

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参考

寄存器选项

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

当 --browser chrome 如果使用，安装程序还会在macOS/Linux上写入通道兼容清单（例如Chrome Stable/Beta/Canary/Chrome for Testing路径），以减少“找不到本机主机”的通道不匹配问题。安装程序还尝试从浏览器配置文件中发现本地解压缩的网页MCP连接器扩展ID，并将其添加到 allowed_origins.

对于具有自定义ID的解包扩展，您可以使用以下方式重新注册：

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

扩展弹出窗口和欢迎页面可以使用以下命令自动生成此命令 chrome.runtime.id，避免了手动ID查找错误。生成的命令可能包括 --force；此标志是可选的。

______________________________________________________________________

技术栈

______________________________________________________________________

故障排除

Extension fails to connect

1. 确保本机主机已注册： npx -y webpage-mcp@latest doctor
2. 检查注册路径上是否有Node.js>=20可用
3. 检查Chrome扩展程序和 webpage-mcp npm包版本匹配，尤其是在新的npm发布之后
4. 更喜欢在扩展弹窗/欢迎中生成的确切注册命令，并运行一次
5. 完全重新启动Chrome（退出所有Chrome进程），然后再次单击“连接”

MCP client can't reach the server

1. 确保Chrome已打开并启用了扩展程序
2. 确保本地主机已连接(npx -y webpage-mcp@latest doctor)
3. 在MCP客户端中使用npx stdio配置(command: "npx", args: ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"])

Tools return errors or time out

1. 确保Chrome已打开并启用了扩展程序
2. 检查扩展的服务工作器控制台是否有错误(chrome://extensions/ >检查视图）
3. 一些工具（例如。， chrome_network_capture)要求特定的页面状态

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

• 触发器：推送和拉取请求 main/develop
• 运行：安装、lint、类型检查（mcp/shared+extension）、测试、构建

release.yml

• 触发器：标签推送 v* 以及人工调度
• 构建发布资产：

- Chrome扩展程序zip(app/chrome-extension/.output/webpage-mcp-connector--chrome-extension.zip) - MCP服务器npm tarball(.tgz) - SHA256SUMS.txt

• 在标签推送时，创建GitHub Release并上传资产
• 标签推送(v*)，发布 webpage-mcp 到npm（需要 NPM_AUTH_TOKEN 秘密）
• 手动npm发布可通过 workflow_dispatch 随着 publish_npm=true

______________________________________________________________________

致谢

该项目基于 hangwin/mcp铬合金特别感谢原作者和所有贡献者的基础工作。

许可证

麻省理工学院