简介一个基于 FastMCP 框架打造的 Playwright MCP Server面向需要为 LLM 应用补足网页操作能力的开发者与自动化测试人员解决在浏览器中模拟表单填写、点击跳转、内容抓取等复杂任务的落地问题。资源包共 26 个文件、约 90KB以 Python 脚本与 Markdown 文档为主体同时附带 YAML 配置、JSON 示例、HTML 说明及打包相关文件目录按源码、测试、文档、示例等模块划分便于快速定位代码、测试与部署说明。目前已有 142 人学习浏览适合有一定 Playwright 使用经验、希望为智能体接入稳定浏览器自动化能力的工程师参考。通过阅读源码结构和示例配置可快速理清基于 FastMCP 的服务器搭建思路获得工具注册、会话处理、错误记录等模块的实践参考尤其适合在大型语言模型应用中需要真实网页交互与数据提取时的二次开发。1. AI能思考不能动手为什么MCP Server最终绕不开浏览器自动化过去这一年我身边越来越多的人在聊MCP聊Agent聊大模型怎么接管真实工作流。但真正动手做过Agent应用的人都会撞上同一个问题模型确实能“思考”可它没有“手”。它写出一段计划容易真要去操作某个系统、读取某个页面、点击某个按钮就完全没辙了。给Agent“装手”的方案并不少有人直接调后端API有人封装命令行工具有人做RPA流程。但你会发现真正高频、通用、绕不开的场景恰恰是操作浏览器。因为浏览器本身就是最大的一扇窗口——它能打开绝大多数Web应用、访问绝大多数信息页面、执行绝大多数交互操作而且不需要目标平台方额外提供任何接口。换句话说只要Agent能控制浏览器它就已经具备了在互联网世界里做大量实际工作的能力。这个项目做的就是把Playwright这套成熟的浏览器自动化引擎包装成一个MCP Server通过FastMCP框架对外暴露工具接口。AI模型只需要按MCP协议的规范发起工具调用就能完成“打开页面、点击元素、填写表单、截取截图、读取文本”这一套真实操作。项目定位很清晰不是做一个Demo而是做一个能扛住真实业务场景的专业级浏览器自动化服务。我从这个项目的实际开发过程中收获了很多也踩了不少坑。网上讲Playwright单点用法的教程很多讲MCP协议的文章也不少但把两者真正结合起来、并且聊清楚工程化设计细节的还真不多。这篇文章就把我的完整实现思路、核心设计决策、踩坑经历都梳理出来希望对正在做类似Agent工具层的朋友有用。2. 为什么不硬调MCP协议FastMCP的价值在于把工具变函数2.1 MCP协议本身的工作机制先看一眼MCP到底是什么。MCPModel Context Protocol是一个开放协议核心目标是让AI应用与外部工具、数据源建立标准化连接。它的通信模型很简单一个MCP Server对外暴露能力经过协议握手后AI客户端可以列举工具列表、调用工具、获取执行结果。协议底层的实现细节并不轻松。你需要处理JSON-RPC消息的封装与解析实现initialize握手机制维护工具列表的注册与查询处理工具调用的请求路由还要考虑不同的传输方式——stdio、HTTP、SSE。如果从零开始硬写框架性的代码占掉大半工作量真正业务逻辑的密度反而很低。我在早期评估过两条路线一条是直接用官方SDK裸写MCP协议层另一条就是用FastMCP这类高层框架。比了一圈下来结论很清楚——项目核心价值在Playwright的工具封装上不在MCP协议的重复实现上。我不希望把时间花在处理消息格式、异常回包、传输层握手这些与业务无关的地方。2.2 FastMCP实际帮我节省了什么工作量FastMCP给我的体验和FastAPI出现之后写后端接口的感觉很像。写MCP工具不需要关心协议细节只需要用装饰器标注的一个普通Python函数框架会自动完成工具注册、参数序列化、返回结果封装这一整套链路。from fastmcp import FastMCP mcp FastMCP(playwright-server) mcp.tool() async def open_page(url: str) - str: 打开指定URL并返回页面标题 page await browser.new_page() await page.goto(url) return await page.title()就这么几行open_page就已经成为一个可供AI客户端调用的MCP工具。FastMCP会自动生成工具描述自动完成参数校验自动把返回值转换为MCP协议的格式。这省掉的不是几行代码而是好几百行协议的框架代码。第二个非常关键的点是传输层。MCP Server可能被不同的客户端以不同的方式接入——本地进程用stdio远程服务用HTTP或SSE。FastMCP在这套项目里直接支持这些模式开发阶段我用stdio本地调试部署阶段切换到HTTP模式供远程服务调用中间不需要改动任何业务代码。第三个值得说的是生命周期管理。FastMCP把MCP的初始化、连接、关闭都封装成了标准的生命周期回调在server启动之前可以做资源初始化关闭之后可以自动清理浏览器进程。这一点对于Playwright这种需要管理外部进程的工具来说尤其重要后面我会详细展开。2.3 用FastMCP自带的其他能力优化项目FastMCP还内置了资源Resources和提示词Prompts的支持虽然这个项目核心是工具调用但我还是用资源能力暴露了一份运行状态报告方便调试的时候快速检查当前有多少个活跃的浏览器上下文。在设置里把include_resources打开就行不用额外写协议代码。有一个细节我建议大家都看看官方文档里的架构设计说明。FastMCP在底层做了懒加载处理工具定义和实际执行是分离的。也就是说即使某个工具在执行过程中抛了异常MCP Server本体不会崩掉只是这个工具调用返回一个错误结果。这对Agent这种高频试错的调用模式来说非常重要。3. 核心工具集设计面向真实网页操作的取舍3.1 工具清单与选型逻辑工具集不该贪多而该精准覆盖操作网页的高频动作。这个项目最终暴露出的核心工具如下工具名作用关键点navigate打开URL跳转页面内置等待load事件避免空页面screenshot截取当前页面截图返回base64兼容MCP的文本协议extract_text提取页面可读文本自动跳过script和style标签click_element点击指定元素支持CSS或Playwright定位器fill_element输入内容到表单字段先清空再输入避免残留值submit_form提交表单顺手处理表单内嵌iframe场景wait_for_selector等待指定元素出现设置超时阈值防止死锁get_element_state获取元素状态支持是否可见、是否可用、是否被选中page_info获取当前页面信息返回URL、标题、描述等元数据list_links列出所有链接用于Agent自主发现可点击目标这套工具集遵循一个核心原则每个工具只做一件清晰的事。不要做一个all_in_one的“万能操作工具”因为AI模型对工具意图的理解越模糊选择就越容易出错。工具边界清晰Agent的调用准确率会明显更高。3.2 定位器策略直接传CSS还是用Playwright Locator关于元素定位这是一个取舍不小的地方。早期版本我直接把CSS选择器透传给Agent让模型自己写selector。实测下来对于id明确的页面、class名规范的项目效果还不错。但真实网页里充满动态class、多层嵌套的DOM结构模型写出的selector经常在页面改版后立刻失效。后面我调整成透传完整的Playwright Locator语法。比如Agent可以传text登录、button:has-text(提交)、[data-testidsubmit-btn]这类更灵活的定位方式。实测下来混合使用CSS和文本定位的召回率比纯CSS高很多。工具定义里定位器参数统一命名为selector但在文档中明确标注支持Playwright Locator语法这样模型才能正确使用。mcp.tool() async def click_element(selector: str, timeout: int 5000) - str: 点击页面元素支持CSS选择器、文本定位等Playwright Locator语法 locator page.locator(selector) await locator.click(timeouttimeout) return f已点击元素: {selector}3.3 等待策略AI调用的稳定性命脉AI调用的浏览器操作和人工操作最大的区别在于模型无法感知页面当前是否渲染完成。人工看到“加载中”会自然等待Agent却可能直接去点击一个还不存在的按钮然后拿到一个timeout错误。所以每个涉及交互的工具都必须内置等待逻辑。navigate之后等待load事件click之前用locator的隐式等待fill之前确保元素处于可编辑状态。最笨的办法就是sleep固定秒数但实测效果很差——网络快的时候浪费时间网络慢的时候照样超时。正确做法是使用Playwright的自动等待机制它会持续轮询元素状态直到满足操作条件或超时。注意超时阈值要可配置默认5000毫秒不要让Agent自己猜。如果页面确实需要更长时间工具参数里显式传入timeout比统一调大更稳妥。4. 会话隔离是关键一个Server同时服务多个Agent的设计4.1 共享浏览器实例会引发什么灾难项目早期版本只维护了一个全局浏览器页面实例。当时想得简单——一个Server服务一个Agent页面资源够用就行。结果一上线就出问题多个客户端并发连接时Agent A正在填写的表单被Agent B的navigate操作冲掉了两个Agent争抢同一个页面的执行权还会出现“screenshot截到的不是自己打开的页面”这种诡异的错误。这个问题让我重新思考整个设计。浏览器自动化服务不能默认自己是单用户环境尤其当一个MCP Server部署在公网或团队内网时并发请求是常态。唯一的正确方案是会话隔离——每个调用者拥有自己独立的浏览器上下文。4.2 基于会话ID的BrowserContext管理方案Playwright本身提供了非常契合这个需求的机制BrowserContext。每个Context就是一个独立的会话环境有自己的Cookie、存储、页面集合互相之间完全隔离。这比给每个会话启动一个完整浏览器进程轻量得多一个浏览器进程里可以承载几十个Context。我按session_id做了一层上下文管理核心数据结构是dict[str, BrowserContext]。每个新的会话连接进来时先从默认浏览器实例创建一个新的Context再在该Context下创建页面。请求结束时不清除Context而是保留一段时间方便同一个Agent连续执行多个操作不丢失页面状态。sessions: dict[str, BrowserContext] {} async def get_context(session_id: str) - BrowserContext: if session_id not in sessions: context await browser.new_context( viewport{width: 1280, height: 800}, user_agentMozilla/5.0 (Windows NT 10.0; Win64; x64) ... ) sessions[session_id] context return sessions[session_id]这里有一个细节值得注意创建Context时要设置viewport和user_agent。不设置的话Playwright默认的无头浏览器UA会被很多网站识别并拦截设置成正常Chrome的UA能规避一大批反爬误伤。这不是为了绕过什么限制而是让自动化工具像真实用户一样正常访问减少被误判的可能性。每个工具函数在入口处先解析session_id参数再基于对应的Context操作。FastMCP的参数注入很方便把session_id定义为工具参数客户端每次调用都带上。这里的取舍是为了隔离的灵活性宁可让每个工具多一个参数也不要为了方便省略而导致状态混乱。4.3 清理与生命周期避免资源泄漏有了会话隔离就必然会面对生命周期管理问题。长时间运行的Server如果只创建Context不销毁最终会把内存和文件句柄耗尽。浏览器进程打开几十个标签页后整个操作系统都会变慢。我用了一个简单但有效的策略记录每个会话的最后活跃时间启动一个后台任务每隔五分钟扫描一次超过30分钟未活动的会话直接关闭Context并清理内存。这样既允许Agent中途思考较长时间又不会让死会话永久占用资源。这个清理机制在FastMCP里通过异步后台任务实现启动server的主函数里把这任务一并拉起随Server生命周期结束而退出。实测下来一个运行7天的服务实例内存占用始终稳定在合理范围内没有出现过泄漏导致服务不可用的情况。5. 实测中踩过的坑从target closed到iframe定位5.1 同步API与异步循环的经典冲突早期我把代码写成同步风格在FastMCP的异步环境中直接用Playwright的同步API。结果出现了一个很隐蔽的bug多个工具连续调用时偶尔会抛出“Event loop is closed”的异常。排查过程花了些时间。原因是FastMCP的事件循环和Playwright同步API的底层实现之间存在冲突——同步API在内部运行了独立的事件循环与FastMCP的主循环抢占资源。最直接的解决方案是全部切换到Playwright的异步API。代码改动量不小但一劳永逸。经验在FastMCP或任何基于async框架的MCP Server中Playwright一定要用async_playwright API。同步API也许在小规模Demo里能跑通但并发一上来问题立刻暴露。5.2 target closed到底什么时候会发生“Target closed”应该是我收到的最多报错也是所有Playwright使用者都见过的问题。这个错误字面意思是“目标页面、上下文或浏览器已关闭”但触发场景比你想象中多得多。最常见的是页面因为某种原因被关闭比如弹窗跳转导致原页面被销毁、用户主动调用了close方法、或者某个导航操作导致页面对象失效。在MCP Server里如果Agent先执行了一个导航操作紧接着又对之前的页面句柄发起点击就很容易复现这个错误。解决思路不是消除所有可能的关闭场景而是每次执行操作前重新获取当前活跃页面。我写了一个helper函数每次工具调用都通过context.pages获取当前页面列表取最后一个活跃的页面来操作。避免长期持有过时的Page对象。async def get_active_page(context: BrowserContext): pages context.pages if not pages: return await context.new_page() # 返回最近活跃的页面通常就是列表中的最后一个 return pages[-1]5.3 动态iframe与shadow DOM的定位思路网页结构里最让人头疼的就是动态iframe。比如一个页面里的富文本编辑器内容区域嵌在iframe里用常规CSS选择器怎么都定位不到。Playwright提供了frame_locator接口可以跨iframe边界操作元素。实战里我建议直接封装一个专门的工具来做iframe内操作而不要指望普通工具能自动穿透。因为页面上可能有多个iframe模型需要明确指定目标iframe的选择器。工具设计上selector参数支持两种格式左侧是iframe选择器、右侧是元素选择器用两个冒号分隔比如iframe[titleeditor]::#content。解析出来后分别调用frame_locator和locator即可。对于shadow DOMPlaywright的locator默认能穿透开放的shadow root。但如果遇到闭合shadow root常规方式就失效了这类场景往往需要注入脚本处理——在封装工具时可以先不做深度支持等有实际需求再加避免一开始就把工具设计得太复杂。5.4 关于浏览器驱动的选择为什么Playwright不需要像Selenium那样手动下载driver在项目讨论群里经常看到有人问Selenium要安装对应版本的浏览器驱动那Playwright该怎么办热词里也出现了“web自动化selenium浏览器驱动怎么判断下载哪个区别”。这个问题的答案是Playwright和Selenium的驱动管理逻辑完全不同。Selenium需要你手动找到与浏览器版本严格匹配的driver文件还要配置系统路径浏览器一升级driver不跟着升级就立刻报错。Playwright则把这一层封装了你只需要执行npx playwright install chromium这条命令它会自动下载与当前Playwright版本兼容的浏览器二进制文件不需要你关心具体版本对应关系。所以在部署MCP Server的服务器上Dockerfile或者初始化脚本里加上这一步环境基本就能跑起来。不要想着去手动下载什么“chromedriver”Playwright体系里压根没有这个东西。对比Python和Node.js两个生态Python版用playwright install chromiumNode.js版用npx playwright install chromium效果一致。理解了这个区别很多初学者在环境搭建上的困惑就能少一大半。5.5 无头模式与截图返回格式生产环境里无头模式是主流选择但调试时必须切换成有头模式观察页面实际状态。我提供了一个配置开关通过环境变量控制浏览器启动模式。有头模式在服务器上跑需要虚拟显示支持不过一般开发机本地调试没问题。截图这个工具要特别注意MCP协议的数据传输以文本为主虽然二进制内容也能传但为了兼容更多客户端截图统一用base64编码后返回。一个1280x800的PNG截图通常有几MBbase64之后更大传输效率并不理想。实测中把图片格式改成JPEG并将质量压到70体积能缩小到原来的十分之一左右对AI理解页面样式的任务来说已经完全够用。工具参数里暴露format和quality让调用方自己决定保真度和体积的平衡。6. 总结这次做Playwright MCP Server的过程其实就是一个典型的“AI Agent工具层工程化”实践。核心并不是Playwright怎么用——Playwright的官方文档已经写得很清楚——而是如何把浏览器操作能力以稳定、安全、会话隔离的方式暴露给AI模型。FastMCP在其中扮演了连接器的角色它让我把精力集中在业务工具和工程细节上而不是协议的重复劳动。根据我个人经验一个能稳定工作的浏览器MCP Server最需要注意的三件事就是会话隔离做好、等待策略给足、生命周期管住。把这三件事都想清楚无论是代码生成、自动化测试还是爬取信息AI模型都能通过这个Server获得可用的真实操作能力。感兴趣的话你可以直接套用上面的工具集设计思路写一个自己的版本然后尝试让Agent连续完成一个多步骤的网页任务感受一下模型“长手”之后的变化。本文还有配套的精品资源点击获取
基于FastMCP与Playwright的浏览器自动化MCP Server设计
简介一个基于 FastMCP 框架打造的 Playwright MCP Server面向需要为 LLM 应用补足网页操作能力的开发者与自动化测试人员解决在浏览器中模拟表单填写、点击跳转、内容抓取等复杂任务的落地问题。资源包共 26 个文件、约 90KB以 Python 脚本与 Markdown 文档为主体同时附带 YAML 配置、JSON 示例、HTML 说明及打包相关文件目录按源码、测试、文档、示例等模块划分便于快速定位代码、测试与部署说明。目前已有 142 人学习浏览适合有一定 Playwright 使用经验、希望为智能体接入稳定浏览器自动化能力的工程师参考。通过阅读源码结构和示例配置可快速理清基于 FastMCP 的服务器搭建思路获得工具注册、会话处理、错误记录等模块的实践参考尤其适合在大型语言模型应用中需要真实网页交互与数据提取时的二次开发。1. AI能思考不能动手为什么MCP Server最终绕不开浏览器自动化过去这一年我身边越来越多的人在聊MCP聊Agent聊大模型怎么接管真实工作流。但真正动手做过Agent应用的人都会撞上同一个问题模型确实能“思考”可它没有“手”。它写出一段计划容易真要去操作某个系统、读取某个页面、点击某个按钮就完全没辙了。给Agent“装手”的方案并不少有人直接调后端API有人封装命令行工具有人做RPA流程。但你会发现真正高频、通用、绕不开的场景恰恰是操作浏览器。因为浏览器本身就是最大的一扇窗口——它能打开绝大多数Web应用、访问绝大多数信息页面、执行绝大多数交互操作而且不需要目标平台方额外提供任何接口。换句话说只要Agent能控制浏览器它就已经具备了在互联网世界里做大量实际工作的能力。这个项目做的就是把Playwright这套成熟的浏览器自动化引擎包装成一个MCP Server通过FastMCP框架对外暴露工具接口。AI模型只需要按MCP协议的规范发起工具调用就能完成“打开页面、点击元素、填写表单、截取截图、读取文本”这一套真实操作。项目定位很清晰不是做一个Demo而是做一个能扛住真实业务场景的专业级浏览器自动化服务。我从这个项目的实际开发过程中收获了很多也踩了不少坑。网上讲Playwright单点用法的教程很多讲MCP协议的文章也不少但把两者真正结合起来、并且聊清楚工程化设计细节的还真不多。这篇文章就把我的完整实现思路、核心设计决策、踩坑经历都梳理出来希望对正在做类似Agent工具层的朋友有用。2. 为什么不硬调MCP协议FastMCP的价值在于把工具变函数2.1 MCP协议本身的工作机制先看一眼MCP到底是什么。MCPModel Context Protocol是一个开放协议核心目标是让AI应用与外部工具、数据源建立标准化连接。它的通信模型很简单一个MCP Server对外暴露能力经过协议握手后AI客户端可以列举工具列表、调用工具、获取执行结果。协议底层的实现细节并不轻松。你需要处理JSON-RPC消息的封装与解析实现initialize握手机制维护工具列表的注册与查询处理工具调用的请求路由还要考虑不同的传输方式——stdio、HTTP、SSE。如果从零开始硬写框架性的代码占掉大半工作量真正业务逻辑的密度反而很低。我在早期评估过两条路线一条是直接用官方SDK裸写MCP协议层另一条就是用FastMCP这类高层框架。比了一圈下来结论很清楚——项目核心价值在Playwright的工具封装上不在MCP协议的重复实现上。我不希望把时间花在处理消息格式、异常回包、传输层握手这些与业务无关的地方。2.2 FastMCP实际帮我节省了什么工作量FastMCP给我的体验和FastAPI出现之后写后端接口的感觉很像。写MCP工具不需要关心协议细节只需要用装饰器标注的一个普通Python函数框架会自动完成工具注册、参数序列化、返回结果封装这一整套链路。from fastmcp import FastMCP mcp FastMCP(playwright-server) mcp.tool() async def open_page(url: str) - str: 打开指定URL并返回页面标题 page await browser.new_page() await page.goto(url) return await page.title()就这么几行open_page就已经成为一个可供AI客户端调用的MCP工具。FastMCP会自动生成工具描述自动完成参数校验自动把返回值转换为MCP协议的格式。这省掉的不是几行代码而是好几百行协议的框架代码。第二个非常关键的点是传输层。MCP Server可能被不同的客户端以不同的方式接入——本地进程用stdio远程服务用HTTP或SSE。FastMCP在这套项目里直接支持这些模式开发阶段我用stdio本地调试部署阶段切换到HTTP模式供远程服务调用中间不需要改动任何业务代码。第三个值得说的是生命周期管理。FastMCP把MCP的初始化、连接、关闭都封装成了标准的生命周期回调在server启动之前可以做资源初始化关闭之后可以自动清理浏览器进程。这一点对于Playwright这种需要管理外部进程的工具来说尤其重要后面我会详细展开。2.3 用FastMCP自带的其他能力优化项目FastMCP还内置了资源Resources和提示词Prompts的支持虽然这个项目核心是工具调用但我还是用资源能力暴露了一份运行状态报告方便调试的时候快速检查当前有多少个活跃的浏览器上下文。在设置里把include_resources打开就行不用额外写协议代码。有一个细节我建议大家都看看官方文档里的架构设计说明。FastMCP在底层做了懒加载处理工具定义和实际执行是分离的。也就是说即使某个工具在执行过程中抛了异常MCP Server本体不会崩掉只是这个工具调用返回一个错误结果。这对Agent这种高频试错的调用模式来说非常重要。3. 核心工具集设计面向真实网页操作的取舍3.1 工具清单与选型逻辑工具集不该贪多而该精准覆盖操作网页的高频动作。这个项目最终暴露出的核心工具如下工具名作用关键点navigate打开URL跳转页面内置等待load事件避免空页面screenshot截取当前页面截图返回base64兼容MCP的文本协议extract_text提取页面可读文本自动跳过script和style标签click_element点击指定元素支持CSS或Playwright定位器fill_element输入内容到表单字段先清空再输入避免残留值submit_form提交表单顺手处理表单内嵌iframe场景wait_for_selector等待指定元素出现设置超时阈值防止死锁get_element_state获取元素状态支持是否可见、是否可用、是否被选中page_info获取当前页面信息返回URL、标题、描述等元数据list_links列出所有链接用于Agent自主发现可点击目标这套工具集遵循一个核心原则每个工具只做一件清晰的事。不要做一个all_in_one的“万能操作工具”因为AI模型对工具意图的理解越模糊选择就越容易出错。工具边界清晰Agent的调用准确率会明显更高。3.2 定位器策略直接传CSS还是用Playwright Locator关于元素定位这是一个取舍不小的地方。早期版本我直接把CSS选择器透传给Agent让模型自己写selector。实测下来对于id明确的页面、class名规范的项目效果还不错。但真实网页里充满动态class、多层嵌套的DOM结构模型写出的selector经常在页面改版后立刻失效。后面我调整成透传完整的Playwright Locator语法。比如Agent可以传text登录、button:has-text(提交)、[data-testidsubmit-btn]这类更灵活的定位方式。实测下来混合使用CSS和文本定位的召回率比纯CSS高很多。工具定义里定位器参数统一命名为selector但在文档中明确标注支持Playwright Locator语法这样模型才能正确使用。mcp.tool() async def click_element(selector: str, timeout: int 5000) - str: 点击页面元素支持CSS选择器、文本定位等Playwright Locator语法 locator page.locator(selector) await locator.click(timeouttimeout) return f已点击元素: {selector}3.3 等待策略AI调用的稳定性命脉AI调用的浏览器操作和人工操作最大的区别在于模型无法感知页面当前是否渲染完成。人工看到“加载中”会自然等待Agent却可能直接去点击一个还不存在的按钮然后拿到一个timeout错误。所以每个涉及交互的工具都必须内置等待逻辑。navigate之后等待load事件click之前用locator的隐式等待fill之前确保元素处于可编辑状态。最笨的办法就是sleep固定秒数但实测效果很差——网络快的时候浪费时间网络慢的时候照样超时。正确做法是使用Playwright的自动等待机制它会持续轮询元素状态直到满足操作条件或超时。注意超时阈值要可配置默认5000毫秒不要让Agent自己猜。如果页面确实需要更长时间工具参数里显式传入timeout比统一调大更稳妥。4. 会话隔离是关键一个Server同时服务多个Agent的设计4.1 共享浏览器实例会引发什么灾难项目早期版本只维护了一个全局浏览器页面实例。当时想得简单——一个Server服务一个Agent页面资源够用就行。结果一上线就出问题多个客户端并发连接时Agent A正在填写的表单被Agent B的navigate操作冲掉了两个Agent争抢同一个页面的执行权还会出现“screenshot截到的不是自己打开的页面”这种诡异的错误。这个问题让我重新思考整个设计。浏览器自动化服务不能默认自己是单用户环境尤其当一个MCP Server部署在公网或团队内网时并发请求是常态。唯一的正确方案是会话隔离——每个调用者拥有自己独立的浏览器上下文。4.2 基于会话ID的BrowserContext管理方案Playwright本身提供了非常契合这个需求的机制BrowserContext。每个Context就是一个独立的会话环境有自己的Cookie、存储、页面集合互相之间完全隔离。这比给每个会话启动一个完整浏览器进程轻量得多一个浏览器进程里可以承载几十个Context。我按session_id做了一层上下文管理核心数据结构是dict[str, BrowserContext]。每个新的会话连接进来时先从默认浏览器实例创建一个新的Context再在该Context下创建页面。请求结束时不清除Context而是保留一段时间方便同一个Agent连续执行多个操作不丢失页面状态。sessions: dict[str, BrowserContext] {} async def get_context(session_id: str) - BrowserContext: if session_id not in sessions: context await browser.new_context( viewport{width: 1280, height: 800}, user_agentMozilla/5.0 (Windows NT 10.0; Win64; x64) ... ) sessions[session_id] context return sessions[session_id]这里有一个细节值得注意创建Context时要设置viewport和user_agent。不设置的话Playwright默认的无头浏览器UA会被很多网站识别并拦截设置成正常Chrome的UA能规避一大批反爬误伤。这不是为了绕过什么限制而是让自动化工具像真实用户一样正常访问减少被误判的可能性。每个工具函数在入口处先解析session_id参数再基于对应的Context操作。FastMCP的参数注入很方便把session_id定义为工具参数客户端每次调用都带上。这里的取舍是为了隔离的灵活性宁可让每个工具多一个参数也不要为了方便省略而导致状态混乱。4.3 清理与生命周期避免资源泄漏有了会话隔离就必然会面对生命周期管理问题。长时间运行的Server如果只创建Context不销毁最终会把内存和文件句柄耗尽。浏览器进程打开几十个标签页后整个操作系统都会变慢。我用了一个简单但有效的策略记录每个会话的最后活跃时间启动一个后台任务每隔五分钟扫描一次超过30分钟未活动的会话直接关闭Context并清理内存。这样既允许Agent中途思考较长时间又不会让死会话永久占用资源。这个清理机制在FastMCP里通过异步后台任务实现启动server的主函数里把这任务一并拉起随Server生命周期结束而退出。实测下来一个运行7天的服务实例内存占用始终稳定在合理范围内没有出现过泄漏导致服务不可用的情况。5. 实测中踩过的坑从target closed到iframe定位5.1 同步API与异步循环的经典冲突早期我把代码写成同步风格在FastMCP的异步环境中直接用Playwright的同步API。结果出现了一个很隐蔽的bug多个工具连续调用时偶尔会抛出“Event loop is closed”的异常。排查过程花了些时间。原因是FastMCP的事件循环和Playwright同步API的底层实现之间存在冲突——同步API在内部运行了独立的事件循环与FastMCP的主循环抢占资源。最直接的解决方案是全部切换到Playwright的异步API。代码改动量不小但一劳永逸。经验在FastMCP或任何基于async框架的MCP Server中Playwright一定要用async_playwright API。同步API也许在小规模Demo里能跑通但并发一上来问题立刻暴露。5.2 target closed到底什么时候会发生“Target closed”应该是我收到的最多报错也是所有Playwright使用者都见过的问题。这个错误字面意思是“目标页面、上下文或浏览器已关闭”但触发场景比你想象中多得多。最常见的是页面因为某种原因被关闭比如弹窗跳转导致原页面被销毁、用户主动调用了close方法、或者某个导航操作导致页面对象失效。在MCP Server里如果Agent先执行了一个导航操作紧接着又对之前的页面句柄发起点击就很容易复现这个错误。解决思路不是消除所有可能的关闭场景而是每次执行操作前重新获取当前活跃页面。我写了一个helper函数每次工具调用都通过context.pages获取当前页面列表取最后一个活跃的页面来操作。避免长期持有过时的Page对象。async def get_active_page(context: BrowserContext): pages context.pages if not pages: return await context.new_page() # 返回最近活跃的页面通常就是列表中的最后一个 return pages[-1]5.3 动态iframe与shadow DOM的定位思路网页结构里最让人头疼的就是动态iframe。比如一个页面里的富文本编辑器内容区域嵌在iframe里用常规CSS选择器怎么都定位不到。Playwright提供了frame_locator接口可以跨iframe边界操作元素。实战里我建议直接封装一个专门的工具来做iframe内操作而不要指望普通工具能自动穿透。因为页面上可能有多个iframe模型需要明确指定目标iframe的选择器。工具设计上selector参数支持两种格式左侧是iframe选择器、右侧是元素选择器用两个冒号分隔比如iframe[titleeditor]::#content。解析出来后分别调用frame_locator和locator即可。对于shadow DOMPlaywright的locator默认能穿透开放的shadow root。但如果遇到闭合shadow root常规方式就失效了这类场景往往需要注入脚本处理——在封装工具时可以先不做深度支持等有实际需求再加避免一开始就把工具设计得太复杂。5.4 关于浏览器驱动的选择为什么Playwright不需要像Selenium那样手动下载driver在项目讨论群里经常看到有人问Selenium要安装对应版本的浏览器驱动那Playwright该怎么办热词里也出现了“web自动化selenium浏览器驱动怎么判断下载哪个区别”。这个问题的答案是Playwright和Selenium的驱动管理逻辑完全不同。Selenium需要你手动找到与浏览器版本严格匹配的driver文件还要配置系统路径浏览器一升级driver不跟着升级就立刻报错。Playwright则把这一层封装了你只需要执行npx playwright install chromium这条命令它会自动下载与当前Playwright版本兼容的浏览器二进制文件不需要你关心具体版本对应关系。所以在部署MCP Server的服务器上Dockerfile或者初始化脚本里加上这一步环境基本就能跑起来。不要想着去手动下载什么“chromedriver”Playwright体系里压根没有这个东西。对比Python和Node.js两个生态Python版用playwright install chromiumNode.js版用npx playwright install chromium效果一致。理解了这个区别很多初学者在环境搭建上的困惑就能少一大半。5.5 无头模式与截图返回格式生产环境里无头模式是主流选择但调试时必须切换成有头模式观察页面实际状态。我提供了一个配置开关通过环境变量控制浏览器启动模式。有头模式在服务器上跑需要虚拟显示支持不过一般开发机本地调试没问题。截图这个工具要特别注意MCP协议的数据传输以文本为主虽然二进制内容也能传但为了兼容更多客户端截图统一用base64编码后返回。一个1280x800的PNG截图通常有几MBbase64之后更大传输效率并不理想。实测中把图片格式改成JPEG并将质量压到70体积能缩小到原来的十分之一左右对AI理解页面样式的任务来说已经完全够用。工具参数里暴露format和quality让调用方自己决定保真度和体积的平衡。6. 总结这次做Playwright MCP Server的过程其实就是一个典型的“AI Agent工具层工程化”实践。核心并不是Playwright怎么用——Playwright的官方文档已经写得很清楚——而是如何把浏览器操作能力以稳定、安全、会话隔离的方式暴露给AI模型。FastMCP在其中扮演了连接器的角色它让我把精力集中在业务工具和工程细节上而不是协议的重复劳动。根据我个人经验一个能稳定工作的浏览器MCP Server最需要注意的三件事就是会话隔离做好、等待策略给足、生命周期管住。把这三件事都想清楚无论是代码生成、自动化测试还是爬取信息AI模型都能通过这个Server获得可用的真实操作能力。感兴趣的话你可以直接套用上面的工具集设计思路写一个自己的版本然后尝试让Agent连续完成一个多步骤的网页任务感受一下模型“长手”之后的变化。本文还有配套的精品资源点击获取
