webshot-mcp

让你的智能体拥有眼睛——无需给它浏览器或你的网络。 一个 MCP 服务器，提供两个工具：screenshot 和 page_text。它可以连接到你已运行的 Chrome（通过 CDP），并捕获整个页面或单个元素。无需启动或下载任何浏览器；私有网络目标会被一个具备 SSRF 感知能力的 URL 策略阻止。

为什么存在这个项目

从使用编程智能体进行视觉检查→修复循环中得出的两个教训：

1. 每次截图都启动一个浏览器是缓慢且不可靠的方式。 一个持久运行的无头 Chromium（Docker 边车、CI 服务、你桌面上的带有 --remote-debugging-port 的 Chrome）是热启动、共享且可靠的。缺少的是一个严谨的客户端：通过 CDP 连接，每次截图打开一个新上下文，只关闭你打开的内容，绝不杀死共享的浏览器。这种严谨性正是这个代码库提供的。

2. 网络内部的截图工具就是一个带摄像头的 SSRF 代理。 如果一个智能体可以被诱导去“截图 http://169.254.169.254/…” 或 http://redis.internal:6379/”，它会愉快地拍摄你的云元数据端点。因此，URL 策略会阻止回环、RFC-1918、链路本地、CGNAT 和 v6 本地目标——包括那些解析到这些地址的主机名——除非你显式地将该主机名加入白名单。本地开发服务器是合理的例外，你需要逐一指定它们。

快速开始

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

获取一个支持 CDP 的 Chrome（任选一个）：

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

接入 Claude Code：

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

然后向智能体提问，比如 “截图 localhost:5173 的英雄区域——只截 .hero——并告诉我哪里不对”：selector 会将画面裁剪到一个元素上，这能让智能体的注意力（以及你的 token）集中在讨论的部分，而不是一整张 4000 像素的页面。

工具

设计说明

• 每次截图使用新上下文，共享浏览器生命周期。 上下文是廉价且隔离的（cookies、缓存、视口）；浏览器是昂贵且共享的。在 CDP 连接上调用 browser.close() 会断开连接，而不会杀死远程浏览器——服务器可以全天重启而不影响 Chrome。

• DNS 会被检查，DNS 重绑定问题已记录。 非 IP 主机名会被解析，并且每个返回的地址都会针对私有范围重新验证。对于截图工具来说，浏览器自身第二次解析时给出不同答案的恶意 DNS 服务器（经典重绑定）超出了范围——这里进行记录而非轻描淡写地跳过。

• deviceScaleFactor: 2——视网膜截图，因为智能体（和人）比你想象的更常误读截图中模糊的文字。

• 策略默认拒绝并且可测试。 evaluateUrl 是一个纯函数，其测试文件中包含了完整的威胁表；服务器在策略批准之前绝不会调用浏览器。

技术栈

TypeScript · @modelcontextprotocol/sdk (stdio) · playwright-core (仅 CDP 客户端——无捆绑浏览器) · zod · vitest。

许可

MIT © Brandon Ta