简介：Playwright MCP Server 是一套基于 FastMCP 框架构建的专业级浏览器自动化服务器，面向需要网页交互与数据提取的开发者及 LLM 应用集成场景。它依托微软 Playwright 跨 chromium、firefox、webkit 的自动化能力，可模拟表单填写、链接点击、内容抓取等操作，并针对自然语言指令处理做了优化，适合复杂网页操作与大规模数据采集任务。资源包共 26 个文件，约 90KB，以 11 个 py 脚本为核心，辅以 5 个 md 文档、2 个 yml 配置、1 个 json 示例及 html、toml、license 等，涵盖服务端逻辑、工具模块、测试用例与部署说明。目录中 server.py、tools、core 等模块划分清晰，examples 提供 claude_desktop_config.json 与 usage_example.py 便于快速接入，docs 内含技术架构与发布配置文档，方便读者理解模块化设计与自定义脚本扩展思路。目前已有 147 人学习，适合希望将浏览器自动化接入 LLM 工作流的开发者参考。
1. 浏览器自动化接进大模型：Playwright MCP Server 到底解决了谁的痛点
你可能已经用 Playwright 写过一堆脚本：登录、填表、截图、抓数据，跑起来挺顺。但当你试图让大模型自己“动手”操作浏览器时，问题就来了——模型只能输出文本，它没法直接点按钮、填输入框、等页面加载。你需要在模型和浏览器之间搭一层协议，把“点击”“输入”“截图”这些动作变成模型能调用的工具。Playwright MCP Server 就是干这个的：它基于 FastMCP 框架，把 Playwright 的浏览器自动化能力封装成 MCP 协议下的工具集，让任何支持 MCP 的客户端（比如某些桌面 AI 工具、IDE 插件、自研 Agent）都能直接调用浏览器操作。适合谁？一是想给自家 Agent 加浏览器能力的后端工程师，二是做自动化测试但想用自然语言驱动的人，三是需要让模型“看见”网页并交互的产品开发者。这一章先把概念立住，后面手把手跑通。
2. 从零搭起 Playwright MCP Server：环境、依赖与最小可运行实例
2.1 为什么选 FastMCP 而不是手写 HTTP 接口
FastMCP 是一个 Python 库，专门用来快速构建 MCP 服务器。它帮你处理了协议握手、工具注册、参数校验、错误封装这些脏活。如果你手写 HTTP 接口，得自己定义路由、解析 JSON-RPC、管理会话状态，还要兼容 MCP 客户端的发现机制。FastMCP 把这些抽象成装饰器：@mcp.tool()一贴，函数就变成模型可调用的工具。Playwright 负责浏览器操作，FastMCP 负责协议转换，两者结合就是 Playwright MCP Server 的核心。选型理由很直接：省去协议层开发，专注浏览器逻辑；社区活跃，遇到问题能搜到答案；Python 生态和 Playwright 无缝衔接。
2.2 安装依赖与初始化项目结构
先建一个干净的虚拟环境，避免和系统里的包打架。我一般用 venv，命令如下：
python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install fastmcp playwright playwright install chromium # 只装 Chromium 减小体积，需要 Firefox/WebKit 再加项目结构建议这样组织，后面扩展工具时不会乱：
playwright-mcp-server/ ├── server.py # 入口，注册工具 ├── browser.py # 浏览器生命周期管理 ├── tools/ │ ├── navigation.py # 导航类工具 │ ├── interaction.py # 点击、输入等 │ └── extraction.py # 截图、取文本 └── requirements.txtbrowser.py里封装一个单例的浏览器上下文，避免每次调用都重启浏览器。关键参数：headless设 True 适合服务器环境，设 False 方便调试；slow_mo加 50~100 毫秒能让模型看清操作节奏，但会拖慢批量任务。
2.3 注册第一个工具：打开网页并返回标题
在server.py里写最小可运行实例：
from fastmcp import FastMCP from playwright.sync_api import sync_playwright mcp = FastMCP("Playwright MCP Server") # 全局浏览器实例，懒加载 _playwright = None _browser = None def get_browser(): global _playwright, _browser if _browser is None: _playwright = sync_playwright().start() _browser = _playwright.chromium.launch(headless=True) return _browser @mcp.tool() def open_page(url: str) -> str: """打开指定 URL 并返回页面标题""" browser = get_browser() page = browser.new_page() try: page.goto(url, timeout=15000, wait_until="domcontentloaded") title = page.title() return f"页面标题: {title}" except Exception as e: return f"打开失败: {str(e)}" finally: page.close() if __name__ == "__main__": mcp.run()逻辑说明：@mcp.tool()把open_page注册为 MCP 工具，模型调用时传url参数。wait_until="domcontentloaded"比默认的load快，适合大多数场景；如果页面有大量异步渲染，改成networkidle但超时要加长。page.close()放在 finally 里防止内存泄漏。参数timeout单位毫秒，15 秒是保守值，内网页面可以降到 5000。
2.4 用 MCP 客户端验证工具是否可用
启动服务器：python server.py。然后用任意 MCP 客户端连接，或者用 FastMCP 自带的测试工具：
from fastmcp import Client async def test(): async with Client("server.py") as client: result = await client.call_tool("open_page", {"url": "https://example.com"}) print(result) import asyncio asyncio.run(test())如果返回页面标题，说明链路通了。常见失败：端口被占、Playwright 浏览器没装、Python 版本低于 3.10。看到Tool not found检查装饰器是否写对；看到Browser closed检查是否在工具外提前关了浏览器。
3. 把点击、输入、截图做成模型能调用的工具：参数设计与状态管理
3.1 点击与输入：选择器策略和等待机制
模型不会写 CSS 选择器，所以工具参数要设计得“傻瓜化”。我一般提供三种定位方式：文本内容、角色+名称、CSS 选择器。优先级：文本 > 角色 > CSS，因为文本最贴近自然语言。
@mcp.tool() def click_element(text: str = None, role: str = None, name: str = None, selector: str = None) -> str: """点击页面元素，支持文本、角色+名称、CSS 选择器三种方式""" browser = get_browser() page = browser.new_page() try: page.goto(current_url, timeout=10000) # current_url 需从会话状态取 if text: page.get_by_text(text, exact=False).first.click(timeout=5000) elif role and name: page.get_by_role(role, name=name).click(timeout=5000) elif selector: page.locator(selector).first.click(timeout=5000) else: return "请提供定位参数" page.wait_for_timeout(500) # 给页面反应时间 return "点击成功" except Exception as e: return f"点击失败: {str(e)}" finally: page.close()参数说明：exact=False允许模糊匹配，模型说“登录按钮”也能点到“登录”。wait_for_timeout(500)是玄学保险，有些 SPA 点击后 DOM 更新慢，不加这行下一步取文本会拿到旧内容。timeout=5000对大多数页面够用，慢页面调到 10000。
3.2 会话状态保持：别让每次调用都开新页面
上面的代码每次new_page()会丢失登录态和当前 URL。正确做法是用一个字典按session_id存 page 对象：
_sessions = {} @mcp.tool() def navigate(session_id: str, url: str) -> str: """在指定会话中导航到 URL""" browser = get_browser() if session_id not in _sessions: _sessions[session_id] = browser.new_page() page = _sessions[session_id] page.goto(url, timeout=15000, wait_until="domcontentloaded") return f"当前页面: {page.title()}" @mcp.tool() def close_session(session_id: str) -> str: """关闭会话释放资源""" if session_id in _sessions: _sessions[session_id].close() del _sessions[session_id] return "会话已关闭" return "会话不存在"模型调用时带上session_id，就能连续操作同一个页面。注意：会话多了会吃内存，建议加一个定时清理，超过 10 分钟没活动的会话自动关掉。
3.3 截图与文本提取：让模型“看见”页面
截图返回 base64 还是文件路径？取决于客户端。支持多模态的客户端直接传 base64，纯文本客户端传路径。我一般两个都返回：
import base64 @mcp.tool() def screenshot(session_id: str, full_page: bool = False) -> dict: """截取当前页面，返回 base64 和保存路径""" page = _sessions.get(session_id) if not page: return {"error": "会话不存在"} path = f"/tmp/screenshot_{session_id}.png" page.screenshot(path=path, full_page=full_page) with open(path, "rb") as f: b64 = base64.b64encode(f.read()).decode() return {"base64": b64, "path": path} @mcp.tool() def get_text(session_id: str, selector: str = "body") -> str: """提取指定元素的文本内容""" page = _sessions.get(session_id) if not page: return "会话不存在" return page.locator(selector).inner_text(timeout=5000)full_page=True会滚动截全页，适合内容长的页面，但图片体积大，base64 可能超客户端限制。get_text默认取 body，模型可以指定selector缩小范围。注意inner_text会等元素出现，超时设 5000 毫秒，页面没加载完就报错。
4. 避坑与排查：Playwright MCP Server 落地时最容易翻车的五个地方
4.1 浏览器启动报错 “Executable doesn't exist”
现象：运行工具时抛异常，提示找不到 Chromium 可执行文件。原因：playwright install没执行，或者虚拟环境切换后没重新装。解决：在激活的虚拟环境里跑playwright install chromium，如果还不行，加--with-deps装系统依赖。Docker 里部署时，基础镜像要带libnss3、libatk-bridge2.0-0这些库，否则 headless 也起不来。
4.2 工具调用超时，但手动跑脚本正常
现象：MCP 客户端调open_page等 30 秒没返回。原因：MCP 客户端默认超时可能只有 10 秒，而页面加载慢。解决：在工具内部把timeout设小一点（比如 8000），并在客户端配置里调大超时。另外检查是不是wait_until="networkidle"导致一直等不到网络空闲，改成domcontentloaded立竿见影。
4.3 点击没反应，但选择器在 DevTools 里能定位
现象：click_element返回成功，但页面没变化。原因：元素被遮挡、在 iframe 里、或者需要先滚动到可视区域。解决：先page.locator(selector).scroll_into_view_if_needed()，再点击。iframe 里的元素要page.frame_locator()切换上下文。遮挡问题用force=True强制点击，但慎用，可能点到错误元素。
4.4 内存涨得飞快，跑几十次就 OOM
现象：服务器跑一段时间后进程被 kill。原因：每次调用都new_page()没关，或者会话字典只增不减。解决：确保每个工具在 finally 里关 page（如果是一次性操作），会话模式加定时清理。另外 Playwright 的 browser context 比 page 更重，别在循环里反复创建 context。
4.5 模型传的参数类型不对，工具直接崩
现象：模型把full_page传成字符串"true"而不是布尔值。原因：MCP 协议虽然会做类型校验，但有些客户端不严格。解决：在工具函数里做防御性转换，比如full_page = str(full_page).lower() == "true"。参数默认值给清楚，模型看到full_page: bool = False会更容易传对。
5. 进阶技巧：用 Playwright MCP Server 做多步任务与结果验证
多步任务的关键是让模型自己决定下一步调什么工具。你不需要写死流程，只要把工具注册好，模型会按需组合。比如“登录后抓取订单列表”这个任务，模型会先调navigate打开登录页，再调click_element点用户名输入框，调type_text输入账号，再点登录，最后调get_text取订单。你可以在工具返回值里加“当前页面标题”和“可见按钮列表”，帮模型判断状态。
验证方法我常用两种：一是回放式验证，把模型调用的工具序列和参数记下来，人工检查是否符合预期；二是断言式验证，在关键步骤后加一个assert_text工具，让模型自己确认页面出现了预期文本。比如：
@mcp.tool() def assert_text(session_id: str, expected: str) -> str: """检查页面是否包含预期文本""" page = _sessions.get(session_id) if not page: return "会话不存在" content = page.locator("body").inner_text() if expected in content: return "验证通过" return f"验证失败，未找到: {expected}"模型在登录后调assert_text(session_id, "欢迎回来")，如果返回失败，它会尝试重新登录或报错。这比你自己写 if-else 灵活得多。
一个具体技巧：给工具返回值加上“建议下一步”。比如click_element成功后返回"点击成功，当前页面有按钮: 提交, 取消"，模型看到就知道下一步可以点提交。这招在复杂表单里特别管用，减少模型瞎猜。
最后说个血泪教训：别让模型直接操作生产环境的浏览器。我一般会起一个独立的浏览器实例，连到测试账号和沙箱数据，并且给每个会话设一个最大操作步数（比如 50 步），超了就强制关闭。后悔药没有，但预防针可以打。希望帮到你。
本文还有配套的精品资源，点击获取
