@linatang/playwright-browser-manager-mcp

Playwright Browser Manager MCP

English | 简体中文

A multi-session Playwright browser manager MCP server for multi-agent and multi-session browser automation.

What problem does it solve?

Plain @playwright/mcp works well for simple single-session workflows, but starts to hurt when multiple agents, threads, or sessions need browsers at the same time.

Common problems:

• shared browser profiles conflict (Browser is already in use)
• a browser gets closed and the session is left with stale page/context handles (Target page, context or browser has been closed)
• callers have to manually manage persistent vs isolated browser state
• reconnect/restart logic leaks into the agent or application layer
• safely reusing already-authenticated browser state is awkward

This MCP solves that by adding a browser-management layer on top of Playwright MCP:

• explicit browser sessions via sessionId
• profile isolation policies
• profile modes (persistent, isolated, fallback-isolated)
• lazy browser launch
• managed session lifecycle
• auto-healing recovery for safe read-only browser calls
• session forking from existing managed sessions

Use this when

Use this MCP if:

• you run multiple agents or sessions that need their own browser state
• you want some sessions to keep login state while others stay isolated
• you hit profile lock errors with plain Playwright MCP
• you want fewer manual reconnect / restart steps after a browser closes unexpectedly
• you want to bootstrap a new session from an existing logged-in managed session

Quick Start

1) Run the MCP server

Option A: run with npx

npx -y @linatang/playwright-browser-manager-mcp@latest

Option B: install globally

npm install -g @linatang/playwright-browser-manager-mcp@latest
playwright-browser-manager-mcp

2) Add it to your MCP client

{
  "mcpServers": {
    "playwright-browser-manager": {
      "command": "npx",
      "args": ["-y", "@linatang/playwright-browser-manager-mcp@latest"]
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "playwright-browser-manager": {
      "command": "playwright-browser-manager-mcp"
    }
  }
}

3) Minimal usage flow

• Call create_session
• Save the returned sessionId
• Call any routed browser tool with that sessionId

Example flow:

• create_session(name="work", profileMode="persistent")
• browser_navigate(sessionId="...", url="https://example.com")
• browser_snapshot(sessionId="...")

How it works

This server starts and manages one Playwright MCP child process per browser session.

Each managed session has:

• a stable sessionId
• a profile policy (persistent, isolated, or fallback-isolated)
• an optional bootstrap source (managed-empty or session)
• lifecycle state (idle, ready, recovering, broken, etc.)
• a routed tool surface that forwards Playwright browser calls to the right session

In other words:

• without this MCP: the caller has to think about browser lifecycle, profile collisions, and state reuse
• with this MCP: the caller mainly thinks in terms of sessionId and browser tasks

Key Features

• Explicit sessionId routing
  Deterministic multi-session automation with no session bleed.

• Profile modes
  Choose the right browser-state policy per session.

• Session forking
  Log in once in a managed session, then fork it to create independent copies with the same state.

• Lazy launch
  Browser child process starts only when a browser tool is first used.

• Auto-healing recovery
  If the browser closes unexpectedly during a safe read-only tool call, the manager tears down the stale child, relaunches, and retries once.

• Managed session lifecycle
  Create, list, close, restart, and fork sessions explicitly.

• Startup tool discovery
  Child Playwright MCP tools are discovered at startup and registered as routed tools.

Profile Modes

Mode	Best for	Behavior
persistent	login state, long-lived browser sessions	Reuses a named local profile directory
isolated	parallel tasks, sandboxed runs, throwaway sessions	Creates a fresh temporary profile for the session
fallback-isolated	prefer persistent state, but avoid hard failure on lock conflicts	Tries the normal profile first, then falls back to a fresh isolated profile if the profile is locked

Getting Auth State into a Managed Session

The recommended approach is to log in directly inside a managed session, then reuse or fork it:

• Create a persistent managed session
• Navigate to your site and log in normally
• Reuse that session for authenticated tasks, or fork it for parallel work

{ "name": "auth-session", "profileMode": "persistent" }

Forking: share auth state across parallel sessions

Use fork_session when you have a managed session with useful browser state (for example, an authenticated session) and want to create independent copies of it.

{
  "sourceSessionId": "session-123",
  "name": "work-agent-2",
  "profileMode": "isolated"
}

Seeding from an existing managed session

You can also initialize a new session from an existing managed session using profileSource:

{
  "name": "new-session",
  "profileMode": "persistent",
  "profileSource": { "type": "session", "sessionId": "session-123" }
}

Auto-Healing and Safe Retry

When a safe read-only browser call fails because the underlying browser/page/context has already closed, the manager will:

• detect the browser-closed error
• tear down the stale child connection
• relaunch the browser session
• retry the failed tool call once

This automatic retry is intentionally limited to safer read-only tools to avoid accidentally double-running mutations.

Currently safe-retry tools include:

• browser_navigate
• browser_snapshot
• browser_take_screenshot
• browser_console_messages
• browser_network_requests
• browser_wait_for

Mutating tools such as click, typing, upload, drag-and-drop, and submit-like interactions are not transparently retried.

Session Lifecycle Tools

This MCP exposes these manager-level tools:

• create_session
• fork_session
• list_sessions
• close_session
• restart_session
• list_local_profiles

All routed Playwright browser tools require a sessionId.

Session Status Reference

Status	Meaning
idle	Session exists but browser has not started yet
launching	Browser is starting
ready	Browser is available and tools can run
recovering	Browser/session is being relaunched after failure
closing	Session is shutting down
closed	Session is stopped and will relaunch on next use
error	Last launch failed; manager will retry on next use
broken	Session could not be recovered automatically
profile_locked	Browser profile is locked by another process

Requirements

• Node.js 20+
• npm
• Network access for npx @playwright/mcp@latest unless already cached locally

Installation

Global install

npm install -g @linatang/playwright-browser-manager-mcp@latest

Local development

npm install
npm run dev

Build and run compiled output

npm run build
npm start

Run tests

npm test

Environment Variables

• PSMCP_PROFILE_ROOT — root directory for browser profiles and session metadata
• PSMCP_DEFAULT_BROWSER — chrome | msedge | chromium
• PSMCP_LOG_LEVEL — log verbosity
• PSMCP_HEADLESS_DEFAULT — true | false
• PSMCP_BROWSER_EXECUTABLE — explicit browser executable path
• PSMCP_PLAYWRIGHT_MCP_COMMAND — override child MCP command
• PSMCP_PLAYWRIGHT_MCP_ARGS — override child MCP args

Troubleshooting

Startup fails at probe discovery

• make sure npx is available
• verify @playwright/mcp can run on this machine
• check outbound network access if you rely on npx @playwright/mcp@latest

Browser launch fails

• check profile directory permissions
• try a different PSMCP_PROFILE_ROOT
• set PSMCP_BROWSER_EXECUTABLE if browser auto-detection is wrong

Session is broken

Use restart_session to force-close and relaunch the session.

Session is profile_locked

Another process may already be using the same browser profile. Create a session with profileMode: "fallback-isolated" if you want automatic fallback behavior.

License

MIT

简体中文

一个面向多 agent / 多 session 浏览器自动化场景的 Playwright Browser Manager MCP 服务。

这个 MCP 解决了什么问题？

原生 @playwright/mcp 在单会话场景下很好用，但一旦你有多个 agent、多个 thread、多个 session 同时需要浏览器，问题就会开始出现。

典型痛点包括：

• 共享浏览器 profile 发生冲突（Browser is already in use）
• 浏览器被关掉后，session 里还握着失效的 page/context 句柄（Target page, context or browser has been closed）
• 调用方需要自己管理 persistent / isolated 两类浏览器状态
• reconnect / restart 逻辑泄漏到 agent 或业务代码里
• 想安全地复用已登录浏览器状态并不顺手

这个 MCP 在 Playwright MCP 之上增加了一层 浏览器管理能力，核心包括：

• 用 sessionId 显式管理浏览器会话
• 用 profile policy 管理浏览器状态隔离
• 支持 persistent、isolated、fallback-isolated 三种 profile 模式
• 按需启动浏览器（lazy launch）
• 管理 session 生命周期
• 对安全的只读调用提供自动恢复（auto-healing）
• 支持从已有 managed session fork 新 session

什么时候该用它？

如果你有这些需求，就很适合用这个 MCP：

• 多个 agent / session 需要各自独立的浏览器状态
• 有的 session 需要保留登录态，有的 session 需要隔离运行
• 你经常遇到 Playwright profile 锁冲突
• 你希望浏览器异常关闭后，尽量少手动 reconnect / restart
• 你希望从已登录的 managed session fork 出新 session

快速开始

1）运行 MCP 服务

方式 A：直接用 npx

npx -y @linatang/playwright-browser-manager-mcp@latest

方式 B：全局安装

npm install -g @linatang/playwright-browser-manager-mcp@latest
playwright-browser-manager-mcp

2）在 MCP client 里配置它

{
  "mcpServers": {
    "playwright-browser-manager": {
      "command": "npx",
      "args": ["-y", "@linatang/playwright-browser-manager-mcp@latest"]
    }
  }
}

如果是全局安装：

{
  "mcpServers": {
    "playwright-browser-manager": {
      "command": "playwright-browser-manager-mcp"
    }
  }
}

3）最小使用流程

• 调用 create_session
• 保存返回的 sessionId
• 后续所有浏览器工具都带上这个 sessionId

示例流程：

• create_session(name="work", profileMode="persistent")
• browser_navigate(sessionId="...", url="https://example.com")
• browser_snapshot(sessionId="...")

它是怎么工作的？

这个服务会为每个浏览器 session 启动并管理一个 Playwright MCP 子进程。

每个受管 session 都有：

• 一个稳定的 sessionId
• 一个 profile 策略（persistent、isolated、fallback-isolated）
• 一个可选的 bootstrap source（managed-empty、session）
• 一套生命周期状态（idle、ready、recovering、broken 等）
• 一组路由后的 Playwright browser tools

可以简单理解成：

• 没有这个 MCP：调用方要自己处理浏览器生命周期、profile 冲突和状态复用
• 有了这个 MCP：调用方主要只需要围绕 sessionId 和浏览器任务来思考

核心特性

• 显式 sessionId 路由 多 session 调用更确定，不容易串会话。

• Profile 模式 每个 session 可以选择适合自己的浏览器状态策略。

• Session Fork 在一个 managed session 里登录一次，然后 fork 出多个独立的子 session。

• Lazy launch 创建 session 时不立即启动浏览器，第一次真正调用浏览器工具时才启动。

• 自动恢复（Auto-healing） 如果浏览器在安全的只读调用过程中意外关闭，manager 会清理失效连接、重新拉起浏览器，并自动重试一次。

• 受管 session 生命周期 支持显式创建、列出、关闭、重启、fork session。

• 启动时自动发现子工具 底层 Playwright MCP 暴露的 browser tools 会在启动时被发现并注册成路由工具。

Profile 模式说明

模式	适合场景	行为
persistent	需要保留登录态、cookie、缓存	复用本地命名 profile 目录
isolated	并行任务、沙盒任务、一次性会话	为当前 session 创建全新的临时 profile
fallback-isolated	希望优先使用 persistent，但 profile 被占用时不要直接失败	先尝试原 profile，若锁冲突则自动回退到新的 isolated profile

如何把登录态带入 Managed Session

推荐做法是直接在 managed session 里登录，然后复用或 fork 它：

• 创建一个 persistent managed session
• 在里面打开网站，正常登录
• 复用这个 session 执行需要认证的任务，或者 fork 出多个并行 session

{ "name": "auth-session", "profileMode": "persistent" }

Fork：在多个并行 session 间共享登录态

当你已经有一个包含有用浏览器状态的 managed session（例如已经登录好的 session），希望再开一个新的独立 session 时，使用 fork_session：

{
  "sourceSessionId": "session-123",
  "name": "work-agent-2",
  "profileMode": "isolated"
}

从已有 managed session 初始化

也可以用 profileSource 从已有 managed session 初始化一个新 session：

{
  "name": "new-session",
  "profileMode": "persistent",
  "profileSource": { "type": "session", "sessionId": "session-123" }
}

自动恢复与安全重试

当安全的只读浏览器调用因为底层 browser/page/context 已关闭而失败时，manager 会：

• 识别浏览器已关闭的错误
• 清理失效的子进程连接
• 重新拉起浏览器 session
• 对失败的工具调用自动重试一次

这个自动重试只适用于更安全的只读工具，避免对带副作用的操作重复执行。

当前支持安全重试的工具包括：

• browser_navigate
• browser_snapshot
• browser_take_screenshot
• browser_console_messages
• browser_network_requests
• browser_wait_for

像点击、输入、上传、拖拽、提交一类可能产生副作用的工具，不会被透明自动重试。

Session 管理工具

这个 MCP 额外提供这些 manager 级工具：

• create_session
• fork_session
• list_sessions
• close_session
• restart_session
• list_local_profiles

所有被路由的 Playwright browser tools 都要求传入 sessionId。

Session 状态说明

状态	含义
idle	session 已创建，但浏览器还没启动
launching	浏览器正在启动
ready	浏览器可用，可以执行工具调用
recovering	浏览器异常后，manager 正在恢复
closing	session 正在关闭
closed	session 已停止，下次使用时会重新拉起
error	上次启动失败，下次使用时 manager 会再试一次
broken	自动恢复失败，需要人工干预
profile_locked	profile 被其他进程占用

运行要求

• Node.js 20+
• npm
• 如果依赖 npx @playwright/mcp@latest，需要机器可以联网

安装

全局安装

npm install -g @linatang/playwright-browser-manager-mcp@latest

本地开发

npm install
npm run dev

构建并运行编译产物

npm run build
npm start

运行测试

npm test

环境变量

• PSMCP_PROFILE_ROOT — 浏览器 profile 和 session 元数据根目录
• PSMCP_DEFAULT_BROWSER — chrome | msedge | chromium
• PSMCP_LOG_LEVEL — 日志级别
• PSMCP_HEADLESS_DEFAULT — true | false
• PSMCP_BROWSER_EXECUTABLE — 指定浏览器可执行文件路径
• PSMCP_PLAYWRIGHT_MCP_COMMAND — 覆盖底层 child MCP 命令
• PSMCP_PLAYWRIGHT_MCP_ARGS — 覆盖底层 child MCP 参数

故障排查

启动阶段 probe discovery 失败

• 确认机器上有 npx
• 确认 @playwright/mcp 可以正常运行
• 如果依赖 npx @playwright/mcp@latest，检查网络访问是否正常

浏览器启动失败

• 检查 profile 目录权限
• 尝试修改 PSMCP_PROFILE_ROOT
• 如果浏览器自动探测不对，显式设置 PSMCP_BROWSER_EXECUTABLE

Session 处于 broken

使用 restart_session 强制关闭并重新拉起 session。

Session 处于 profile_locked

说明同一个 profile 正被别的进程占用。如果你希望自动回退，可以创建一个 profileMode: "fallback-isolated" 的 session。

License

MIT