nstbrowser-playwright-mcp

MCP server that combines NSTBrowser profile management with Playwright browser automation via CDP (Chrome DevTools Protocol).

Built on top of the official @playwright/mcp package — all browser automation tools are provided by Microsoft's Playwright MCP server, connected to NSTBrowser profiles via CDP.

Features

• 26 MCP tools — 20 browser automation tools (from @playwright/mcp) + 6 session/profile management tools

• Connect to existing NSTBrowser profiles or create temporary ones

• Multi-session support with session switching

• Full Playwright browser automation: navigation, clicking, typing, screenshots, JavaScript evaluation, drag & drop, form filling, and more

• Console log and network request tracking

• Accessibility snapshots for AI-driven interaction

Related MCP server: browser-mcp-server

Prerequisites

• Node.js >= 20

• NSTBrowser installed and running

• An NSTBrowser API key

Quick Start

Claude Code

claude mcp add nstbrowser -- npx -y nstbrowser-playwright-mcp

Then set your API key in the environment or pass it via --env:

claude mcp add nstbrowser -e NSTBROWSER_API_KEY=your-api-key-here -- npx -y nstbrowser-playwright-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nstbrowser": {
      "command": "npx",
      "args": ["-y", "nstbrowser-playwright-mcp"],
      "env": {
        "NSTBROWSER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or Windsurf equivalent):

{
  "mcpServers": {
    "nstbrowser": {
      "command": "npx",
      "args": ["-y", "nstbrowser-playwright-mcp"],
      "env": {
        "NSTBROWSER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Install from source

git clone https://github.com/jackie099/nstbrowser-playwright-mcp.git
cd nstbrowser-playwright-mcp
npm install
npm run build

Configuration

Environment Variables

Available Tools

Session Management

Browser Automation (from @playwright/mcp)

These tools are automatically available after creating your first session. They are provided by the official Playwright MCP server and use accessibility snapshot refs (element/ref) for targeting elements.

NSTBrowser Management

create_session Parameters

All parameters are optional. When no profileId is provided, a temporary profile is created. The NSTBrowser API applies sensible defaults for any omitted fields (see NSTBrowser API docs for details).

Usage Examples

Connect to an existing profile

Use create_session with profileId "abc123" to connect to my NSTBrowser profile,
then navigate to https://example.com and take a screenshot.

Create a temporary session (no arguments needed)

Create a temporary browser session and navigate to https://news.ycombinator.com.
Get an accessibility snapshot of the page.

Create a temporary session with custom settings

Create a session with platform "windows" and kernelMilestone "132",
then navigate to https://example.com.

Multi-session workflow

Create two sessions - one for GitHub and one for Gmail.
Switch between them to check notifications on both.

How It Works

1. Session creation — When you call create_session, the server connects to NSTBrowser's API to get a CDP (Chrome DevTools Protocol) WebSocket URL for the requested profile.

2. Playwright MCP bridge — The CDP endpoint is passed to @playwright/mcp's createConnection, which creates a full Playwright MCP server instance connected to that browser.

3. Tool proxying — On the first session creation, browser tools are discovered from the Playwright MCP instance and registered as proxy tools on our server. Tool calls are forwarded to the active session's Playwright MCP client.

4. Multi-session — Each session has its own Playwright MCP connection. Switching sessions routes all browser tool calls to the new active session.

Development

npm install
npm run build
npm test
npm run lint

License

MIT