MCP Webmcp

@技术峰会/mcp-webmcp

](https://www.npmjs.com/package/@tech-sumit/mcp-webmcp)

连接浏览器的MCP服务器 WebMCP 工具到桌面AI应用程序。通过Playwright连接到Chrome，并通过模型上下文协议公开26个浏览器自动化工具+WebMCP元工具。

安装

npm install -g @tech-sumit/mcp-webmcp

或者直接使用npx运行（无需安装）：

npx -y @tech-sumit/mcp-webmcp

快速开始

选项1：启动时自动启动浏览器(--launch)

添加到MCP客户端配置(~/.cursor/mcp.json 或克劳德桌面）：

{
  "mcpServers": {
    "mcp-webmcp": {
      "command": "npx",
      "args": ["-y", "@tech-sumit/mcp-webmcp", "--launch"]
    }
  }
}

服务器启动Chrome Beta时启用了WebMCP。所有26种工具均可立即使用。

选项2：让AI代理启动浏览器（默认）

{
  "mcpServers": {
    "mcp-webmcp": {
      "command": "npx",
      "args": ["-y", "@tech-sumit/mcp-webmcp"]
    }
  }
}

没有 --launch，所有26个工具都已注册，但没有启动浏览器。AI代理调用 browser_launch 当它需要浏览器时，可以使用该工具。这使客户端可以完全控制浏览器何时以及如何启动。

建筑

graph TD
    subgraph mcp_webmcp ["MCP-WebMCP Server"]
        PB["PlaywrightBrowserSource
24 browser tools + 2 WebMCP meta-tools"]
        TR[ToolRegistry]
        MCP["MCP Server"]
    end

    subgraph transport ["Transport Layer"]
        STDIO["stdio
(default, for mcp.json)"]
        HTTP["HTTP /mcp
:3100 (optional)"]
    end

    subgraph browser_modes ["Browser Connection"]
        Launch["--launch
chromium.launch()"]
        CDP["CDP :9222
connectOverCDP()"]
    end

    Launch --> PB
    CDP --> PB
    PB --> TR
    TR --> MCP
    MCP --> STDIO
    MCP --> HTTP

    STDIO --> Cursor["Cursor"]
    STDIO --> Claude["Claude Desktop"]
    HTTP --> Any["Any MCP Client"]

连接模式

运输方式

先决条件

检查您的Chrome版本

# macOS — Chrome Beta
/Applications/Google\ Chrome\ Beta.app/Contents/MacOS/Google\ Chrome\ Beta --version

# macOS — Chrome Canary
/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary --version

# Linux
google-chrome-beta --version

# Windows
"C:\Program Files\Google\Chrome Beta\Application\chrome.exe" --version

服务器在启动时验证Chrome>=146，如果版本太旧，将抛出一个明确的错误。

设置

光标

增添 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-webmcp": {
      "command": "npx",
      "args": ["-y", "@tech-sumit/mcp-webmcp"]
    }
  }
}

添加 "--launch" 到 args 如果你想让Chrome在启动时打开。

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-webmcp": {
      "command": "npx",
      "args": ["-y", "@tech-sumit/mcp-webmcp"]
    }
  }
}

本地开发

{
  "mcpServers": {
    "mcp-webmcp": {
      "command": "node",
      "args": ["/path/to/dist/cli.js"]
    }
  }
}

HTTP传输（托管服务器）

对于手动或托管使用，请将服务器作为HTTP端点运行：

mcp-webmcp start [--launch] [--port 3100]

将您的MCP客户端连接到 http://localhost:3100/mcp.

自动配置

mcp-webmcp config cursor   # writes ~/.cursor/mcp.json
mcp-webmcp config claude    # writes Claude Desktop config

选项

可用工具（26）

工具类别

graph TD
    subgraph browser_auto ["Browser Automation (24 tools)"]
        direction LR
        Nav["Navigation
navigate, back, forward, reload"]
        State["Page State
url, snapshot, screenshot
console_logs, network_requests"]
        Interact["Interaction
click, type, fill, hover
select_option, press_key, focus"]
        Scroll["Scrolling
scroll"]
        Tabs["Tab Management
tab_list, tab_new
tab_select, tab_close"]
        JS["JavaScript
evaluate"]
        Wait["Wait
wait"]
        Lifecycle["Lifecycle
launch"]
    end

    subgraph webmcp_meta ["WebMCP Meta-Tools (2 tools)"]
        direction LR
        List["webmcp_list_tools
Discover page tools"]
        Call["webmcp_call_tool
Execute page tools"]
    end

浏览器自动化（24个工具）

WebMCP元工具（2个工具）

WebMCP工具是 动态的 --当用户在页面之间导航时，它们会发生变化。总是打电话 webmcp_list_tools 之前 webmcp_call_tool 以发现可用的内容。

元素定位：快照+引用

sequenceDiagram
    participant Agent
    participant Server
    participant Page

    Agent->>Server: browser_snapshot
    Server->>Page: ariaSnapshot()
    Page-->>Server: Accessibility tree
    Note over Server: Assigns [ref=N] to each element
    Server-->>Agent: Annotated snapshot

    Note over Agent: Picks ref=5 for Submit button

    Agent->>Server: browser_click {ref: 5}
    Note over Server: Resolves ref=5 via getByRole().nth()
    Server->>Page: Click resolved locator
    Page-->>Server: Done
    Server-->>Agent: Clicked button Submit ref=5

CLI参考

mcp-webmcp （默认--stdio模式）

作为stdio MCP服务器运行。这就是 mcp.json 调用。

mcp-webmcp [options]

mcp-webmcp start （HTTP模式）

通过HTTP启动MCP服务器。

mcp-webmcp start [options]

与stdio模式相同的选项，另外：

mcp-webmcp list-tools

列出连接的浏览器选项卡中的所有WebMCP工具（直接使用CDP）。

mcp-webmcp list-tools [--host localhost] [--port 9222]

mcp-webmcp call-tool [args]

按名称执行WebMCP工具。

mcp-webmcp call-tool searchFlights '{"from":"SFO","to":"JFK"}'

mcp-webmcp config

编写MCP客户端配置（基于stdio）。

mcp-webmcp config cursor   # writes ~/.cursor/mcp.json
mcp-webmcp config claude    # writes Claude Desktop config

演示：通过WebMCP预订餐桌

此演示显示了完整的流程：AI代理使用 browser_launch 打开Chrome浏览器，导航到启用WebMCP的餐厅页面，发现 book_table_le_petit_bistro 工具和预订桌子——所有这些都是通过MCP完成的。

代理工作流

sequenceDiagram
    participant Agent as AI Agent (Cursor)
    participant MCP as MCP-WebMCP
    participant Chrome as Chrome Browser
    participant Page as Le Petit Bistro

    Agent->>MCP: browser_launch {channel: "chrome-beta"}
    MCP->>Chrome: chromium.launch()
    Chrome-->>MCP: Browser ready
    MCP-->>Agent: "Launched chrome-beta"

    Agent->>MCP: browser_navigate {url: "localhost:5173"}
    MCP->>Chrome: page.goto()
    Chrome-->>MCP: Page loaded
    MCP-->>Agent: "Le Petit Bistro"

    Agent->>MCP: webmcp_list_tools
    MCP->>Page: navigator.modelContextTesting.listTools()
    Page-->>MCP: [{name: "book_table_le_petit_bistro", ...}]
    MCP-->>Agent: Tool schema with inputs

    Agent->>MCP: webmcp_call_tool {name: "book_table_le_petit_bistro", ...}
    MCP->>Page: navigator.modelContextTesting.executeTool(...)
    Page-->>MCP: "Reservation confirmed"
    MCP-->>Agent: "Hello Sumit, We look forward to welcoming you..."

发生了什么

1. browser_launch 打开Chrome测试版 --enable-features=WebMCPTesting
2. browser_navigate 加载Le Petit Bistro预订表
3. webmcp_list_tools 发现 book_table_le_petit_bistro 及其完整的输入模式（姓名、电话、日期、时间、客人、座位、请求）
4. webmcp_call_tool 预订表格——表格会自动填充，并出现一个确认模式： *“已收到预订——祝您胃口好！”*

故障排除

决策树

flowchart TD
    Problem(["Something went wrong"]) --> Q0{"Using --launch mode?"}
    Q0 -- Yes --> Q0a{"Chrome Beta/Canary
installed?"}
    Q0a -- No --> F0["Install Chrome Beta
chrome.google.com/beta"]
    Q0a -- Yes --> Q3
    Q0 -- No --> Q1{"Can you reach Chrome?
curl localhost:9222/json/version"}
    Q1 -- No --> F1["Launch Chrome with
--remote-debugging-port=9222"]
    Q1 -- Yes --> Q2{"Chrome version >= 146?"}
    Q2 -- No --> F2["Install Chrome Beta/Canary"]
    Q2 -- Yes --> Q3{"Server starts?"}
    Q3 -- No --> F3["Check error message in stderr"]
    Q3 -- Yes --> Q4{"MCP client connects?"}
    Q4 -- No --> F4["Check mcp.json config
Toggle MCP off/on"]
    Q4 -- Yes --> Q5{"WebMCP tools work?"}
    Q5 -- No --> F5["Ensure --enable-features=WebMCPTesting
(--launch adds it automatically)"]
    Q5 -- Yes --> OK(["Everything working"])

常见问题

“不支持Chrome X版本”

您的Chrome浏览器已超过146。安装Chrome测试版或Canary：

• https://www.google.com/chrome/beta/
• https://www.google.com/chrome/canary/

“WebMCP不可用”

Chrome不是用 --enable-features=WebMCPTesting。如果使用CDP模式，请关闭所有Chrome窗口，然后使用该标志重新启动。启动模式(--launch)自动添加此标志。

“未找到浏览器上下文”

Chrome未运行 --remote-debugging-port=9222，或者它没有打开选项卡。使用 --launch 模式，或用以下方式验证：

curl http://localhost:9222/json/version

目标页面、上下文或浏览器已关闭

浏览器连接丢失。使用 browser_launch 工具启动新浏览器或重新启动MCP服务器。

屏幕截图超时

Playwright在截图之前等待网络字体加载。服务器使用10秒的超时来避免挂起。

在模态/叠加元素上点击失败

元素在 position: fixed 覆盖可能无法滚动到视图中。服务器会自动重试 force: true 直接单击元素的坐标。

发展

pnpm install           # install dependencies
pnpm build             # compile with tsup → dist/
pnpm dev               # watch mode
pnpm start             # run HTTP server (CDP mode)
pnpm start:stdio       # run stdio server
pnpm typecheck         # tsc --noEmit
pnpm lint              # eslint
pnpm test              # vitest
pnpm format            # prettier

许可证

麻省理工学院