企业官网建设流程全解析

• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务

本篇指南以 Cursor 编辑器为客户端，讲解如何把 invisible_playwright_mcp 的隐形浏览器接入 Cursor：包括项目级与全局级两处 mcp.json 配置的取舍、Cursor 自动选择工具与默认审批的运行机制、两条可以立刻上手验证的首批提示词，以及首次运行时最常遇到的五个问题的排查路径。读完你就能在 Cursor 里让 AI 代理驱动一台真实的补丁版 Firefox——点击、输入、截图、读页面——并用它来驱动和测试你自己的 Web 应用。

平台边界：先确认你的机器在支持列表里

在动手配置之前，先确认一个硬性前提。invisible_playwright_mcp 的引擎目前为 Windows（x86_64）和 Linux（x86_64、arm64）提供构建，没有 macOS 构建。也就是说，在 Mac 上 Cursor 可以正常启动 MCP server，但 server 会发现没有任何引擎可以运行——"It is a Mac. No engine build; nothing to debug." 这一组合（Cursor + invisible_playwright_mcp）目前只在 Windows 和 Linux 上是可用的。如果你在 macOS 上遇到了"服务器启动了但浏览器毫无反应"，不必继续排查，这是平台支持边界而非配置错误。

关于引擎本身的更多事实可以核对 README.md 与 server.json：包名是io.github.feder-cr/invisible-playwright-mcp，以 stdio 传输方式运行，发布到 PyPI，由uvx启动。

Cursor 读取 MCP 的方式：项目级与全局级两处配置

Cursor 从一个 JSON 文件读取 MCP 服务器配置，按 Cursor 自己的文档定义有两个层级：

• 项目级：.cursor/mcp.json，放在项目仓库内，工具仅对该项目生效；
• 全局级：~/.cursor/mcp.json，放在用户主目录，工具对所有项目可用。

两个位置粘贴的配置块完全相同，配置块本身存放在本仓库的 mcp-server.md 页面（原文即"链接而非复制"该页，本页负责讲 Cursor 侧的故事）。这个配置块只告诉客户端"如何启动 server"，内容形如：

{ "mcpServers": { "invisible_playwright_mcp": { "type": "stdio", "command": "uvx", "args": ["invisible-playwright-mcp"] } } }

这正是仓库根目录 mcp.json 中实际携带的配置：command: "uvx"、args: ["invisible-playwright-mcp"]、stdio 传输。server 名（键名，如invisible_playwright_mcp或 mcp-server.md 示例里的stealth）可以随意起，不影响行为。启动的前提是先安装好uv——README 的安装章节给出了 Windows PowerShell 与 Linux 两条安装命令，装好后uvx才能被找到。

需要额外的代理、种子、配置文件等设置时，把它们放在 server 条目的env下（详见下文"环境变量"一节），例如：

{ "mcpServers": { "invisible_playwright_mcp": { "command": "uvx", "args": ["invisible-playwright-mcp"], "env": { "STEALTHFOX_PROXY": "http://user:pass@proxy.example.com:8080", "STEALTHFOX_SEED": "4242" } } } }

层级选择取决于受众：

• 全局级适合个人研究工具——浏览器在所有项目里都可用；
• 项目级跟随仓库走，适合希望"agent 能驱动我们的 staging 应用"成为团队 checkout 体验的一部分。

一个关键的安全结论：server 配置块只含命令与参数，不含任何 key 或 secret——模型由 Cursor 自带，invisible_playwright_mcp 这边没有任何需要注册的东西——所以把它提交进仓库是"配置提交"里最安全的一类。是否愿意把编辑器工具链放进仓库是团队决策，而不是安全问题。需要说明的是，虽然配置块本身无 secret，但若你在env里填写了代理认证信息，请留意该 JSON 文件会被提交，敏感信息应通过环境变量而非仓库文件传递。

一个浏览器在编辑器里真正能做什么：诚实的边界

Cursor 的 agent 本来就能读你的代码、能搜索网页。一台可驱动的浏览器是另一种能力，值得精确界定它什么时候值得存在——因为对一次快速查文档来说，它是杀鸡用牛刀：

• 需要"驱动页面"而不是"抓取页面"的研究。版本切换器后面的文档、滚动加载的 changelog、需要连点三个产品页的对比页——任何"答案需要你在页面上操作而不是一次性下载下来"的场景，浏览器才派得上用场。
• 用一个贴近真实的浏览器测试你自己的 Web 应用。这是编辑器原生场景：把 agent 指向你的 dev server，让它注册一个用户、走一遍 checkout 向导、或者在你刚写的表单上反复触发校验，然后汇报它看到了什么。浏览器是真实的补丁版 Firefox，它渲染出的内容、发出的事件与一个人用真实浏览器时一致——真实按键与点击，而非脚本注入的值。由于同一个 agent 同时看得到你的代码，"在应用里复现这个 bug，然后看一下 handler 告诉我为什么"可以是一段对话里完成的事。
• 读取那些对普通抓取工具"回推"的页面。一个对简单 HTTP fetch 几乎不返回内容的页面，经真实浏览器可能读得很好。当站点回推超出这个程度时，诚实的归因地图在 why-does-my-ai-agent-get-blocked.md，没有任何工具能保证带你穿过它。

它不添加的是：速度。一个浏览器会话加上模型推理轮次，是慢而审慎的路径。如果一条curl就能回答的问题，浏览器就是错误的工具——这个边界正是 ai-browser-agents-vs-traditional-scraping.md 长篇论述的分界线。

Cursor 如何运行这些工具：自动选择、默认审批、可开关

关于运行侧，Cursor 自己的文档明确了两个关键行为：agent 在判断工具相关时会自动使用 MCP 工具，且默认情况下每次运行工具前都会征求你的批准，并提供设置让白名单工具免审批运行。服务器也可以从 Cursor 的设置里直接开关，无需删除配置。实际后果是：你不直接"调用工具"，而是描述目标、逐步批准；如果你不想在某个项目里继续用浏览器，"开关"优于"编辑 JSON"。

工具本身分为两个家族：

• 浏览器工具：browser_open及其同族（browser_close、browser_list、browser_status）；
• 页面工具：browser_navigate、browser_read_text、browser_snapshot、browser_click、browser_type、browser_take_screenshot等。

完整清单（含browser_read_html、browser_watch、browser_click_at、browser_select_option、browser_press_key、browser_evaluate）见 mcp-server.md 的工具表。你在 agent 的工作转录里看到的正是这些名字，每一项在放宽之前都由一次批准把守。从源码看，actions_help.py 把这些调用翻译成一行可读摘要（browser_navigate显示 URL、browser_click显示 selector、browser_type对疑似密码字段只显示hidden, N characters），这也是为什么你可以在 Cursor 里舒服地旁观每一步在做什么。

首批提示词：先测安装，再测你自己的应用

第一条提示词是安装测试，所以它应该足够小、足够可检查：

Open https://books.toscrape.com/ and tell me the title and price of the first book on the page.

这个示例站点是专门用于练习的沙箱。如果这条成功了，整条链路就通了：server 启动、引擎就位、页面加载、文本读取。

然后是编辑器原生场景，指向你自己的东西：

Start the dev server's page at http://localhost:3000. Register a new user through the signup form with placeholder data, do not submit the final step, and list every validation message you encounter on the way.

关于这条提示词有两点说明：

• "Do not submit"（不要提交）是刻意的：把"会产生后果的那一下点击"留给真人，是 ai-agent-fill-out-forms.md 的一贯建议，一旦数据是真实的，它同样适用于你自己的应用；
• localhost 目标让你最初的几次会话停留在"犯错不花钱"的地方。

浏览器默认是无头（headless）模式，因此 agent 的截图（browser_take_screenshot）就是你观察"发生了什么"的窗口。当你想直接看着它驱动你的应用时，server 从自己的环境读取STEALTHFOX_HEADLESS=0，设置在同一份配置块的env里：

{ "mcpServers": { "invisible_playwright_mcp": { "command": "uvx", "args": ["invisible-playwright-mcp"], "env": { "STEALTHFOX_HEADLESS": "0" } } } }

其余环境变量在 mcp-server.md 有完整文档；其中持久化 profile 目录（STEALTHFOX_PROFILE_DIR，登录态跨运行保留）和固定身份种子（STEALTHFOX_SEED，同一种子同一指纹）是反复测试时最有用的两个。从源码看，这份设置的传播路径是清晰的：cli.py 的浏览器选项（--headed等）在 runner.py 的child_env中被映射为STEALTHFOX_HEADLESS=0等环境变量交给引擎，而 mcp/plan.py 用env.get("STEALTHFOX_HEADLESS", "1") != "0"决定一次启动是否无头——默认值是1，即无头。

常见首次运行问题与排查

1. 第一条触碰页面的提示词回答"引擎正在下载"。引擎约有四分之一 GB，由 server 在 Cursor 启动它的那一刻起自行抓取；在下载完成前请求浏览器，得到的是下载进度，agent 会在一分钟后再问一次。想把它提前到你自己选定的时刻，在终端里预取一次：

   uvx invisible-playwright fetch

   引擎会被缓存，并与进入 invisible_playwright_mcp 的每一条其他路径共享。源码侧的解释在 engine.py：这个下载此前发生在"README 的 fetch 行"或"第一次浏览器启动"两处之一，而后者在 MCP 客户端看来就是一次卡住数分钟的工具调用；现在它成了 server 进程启动后自行做一次的事情，browser_open在引擎未就绪时只回报进度并要求再次调用，任何工具调用都不会被它阻塞。FETCH_BY_HAND（uvx invisible-playwright fetch）在 engine.py 被定义为一处命名，保证错误提示与 setup 技能说同一句话。

2. server 没有出现在 Cursor 的 MCP 列表里。检查 JSON、确认文件位于上文两个文档位置之一、并确认uvx对 Cursor 可解析：配置是用uvx启动 server 的，所以uv 必须装在编辑器能找到它的地方——这并不由"它在某个特定 shell 里能用"来保证。安装方式见 README.md。

3. 工具都在，但每一步都要求批准。这就是文档化的默认行为，在你还处于"了解浏览器能做什么"的阶段时，请保持它开启。Cursor 的设置允许在你信任该模式后加入白名单；要放宽也是刻意为之，而不是第一天就放宽。

4. 是 Mac。没有引擎构建，没什么可排查的——回到本文开头的平台边界。

5. 某个公开站点加载异常或回推。在碰配置之前，先把层次分开：本地一半看 browser-problem-or-model-problem.md，站点一半看 why-does-my-ai-agent-get-blocked.md。注意 mcp-server.md 的 Notes 也写明："这是一个浏览器，不是验证码求解器"——它不会替你解谜或绕过挑战，它只是让一次普通的 Firefox 会话看起来像真的。

常见问题速答

怎么把 invisible_playwright_mcp 的浏览器加进 Cursor？把 mcp-server.md 里的配置块粘贴到项目内的.cursor/mcp.json或全局的~/.cursor/mcp.json，两个位置都符合 Cursor 自己的 MCP 文档。无 key、无注册，思考由 Cursor 的模型完成。

配置应该项目级还是全局级？个人研究工具选全局；团队希望能力随仓库版本化时选项目级。配置块不携带 secret，所以这是作用域问题，不是安全问题。

Cursor 的 agent 会自己使用浏览器吗？它在判断相关时会自动选择 MCP 工具，但默认每次工具运行都等待你的批准；"白名单化以自动运行"是之后你主动选择加入的设置。

这在编辑器里到底擅长什么？通过真实浏览器驱动和测试你自己的 Web 应用，以及需要"在页面上操作"而非"抓取页面"的研究。查个资料普通搜索就能回答时，跳过浏览器。

为什么第一条指令说引擎正在下载？引擎下载：约四分之一 GB，由 server 在 Cursor 启动它时开始，browser_open持续报告进度直到完成。在终端执行uvx invisible-playwright fetch可以把这笔成本挪到你选定的时刻。

我能看着浏览器工作吗？默认不能——它是无头的，截图工具就是你的窗口。在 server 的环境块里设置STEALTHFOX_HEADLESS=0就能得到真实窗口，在它驱动你自己的应用时这确实有用。

继续阅读

• 配置块、完整工具表与环境变量：mcp-server.md
• 其它客户端接入方式：running-invisible-playwright-mcp-with-claude-code.md、running-invisible-playwright-mcp-with-claude-desktop.md
• 让 AI agent 填表：ai-agent-fill-out-forms.md
• 把 agent 采集的数据导出为 CSV：how-to-extract-data-to-csv-with-an-ai-agent.md
• 被拦截时的分层排查：browser-problem-or-model-problem.md、why-does-my-ai-agent-get-blocked.md

最后借用本 wiki 的一句话收尾：invisible_playwright_mcp 在 Cursor 里最强、也最不引人注目的用法，是让 agent 去填你自己那半成品的表单——填得很糟，然后精确地告诉你它在哪一步断了。

• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务