playwright-mcp-server

A small, self-contained Playwright helper you can drop into other Node projects.

Use it as:

1. A class — PlaywrightSessionManager opens isolated browser sessions, then gives you the real Playwright page when you need click, fill, screenshot, or anything else.

2. An MCP server — the same manager exposed as tools over stdio, so an agent can drive a browser.

Node 20+ and Chromium (via Playwright) are the only runtime requirements.

Install in another project

From GitHub:

npm install github:james8128/playwright-mcp-server
npx playwright install chromium

From a local clone:

npm install ../playwright-mcp-server
npx playwright install chromium

This package depends on playwright. After install, Chromium still needs a one-time browser download (npx playwright install chromium).

Related MCP server: mcp-browser

30-second library use

import { PlaywrightSessionManager } from "playwright-mcp-server";

const pw = new PlaywrightSessionManager();

const { sessionId, title } = await pw.openPage({
  url: "https://example.com",
  headless: true,
});

console.log(title);

await pw.use(sessionId, async ({ page }) => {
  await page.screenshot({ path: "example.png" });
});

await pw.close(sessionId);

use() is the escape hatch. Anything Playwright can do, you can do inside that callback while the session stays locked and alive.

Full method list: docs/api.md.

MCP server

npm start
# same as: node server.js

Point an MCP client at node /path/to/playwright-mcp-server/server.js.

Tools: openPage, getTitle, waitForElement, listSessions, closeBrowser, closeAll.

Details: docs/mcp.md.

Why this exists

Raw Playwright works, but a long-running helper still has to:

• isolate each job in its own browser context

• close browsers on failed navigation and on process exit

• cap how many sessions can exist

• time out idle sessions

• reject non-http(s) URLs

• serialize work so close cannot race with a click

That is what PlaywrightSessionManager does. Other projects should not have to reimplement it.

Layout

Scripts

npm test                 # unit + Chromium integration tests
npm start                # run the MCP server on stdio
npm run install-browser  # download Chromium for Playwright

Defaults

License

ISC. See LICENSE.