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

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

Variable	Required	Default	Description
NSTBROWSER_API_KEY	Yes	—	Your NSTBrowser API key
NSTBROWSER_API_ADDRESS	No	http://localhost:8848/api/v2	NSTBrowser API endpoint

Available Tools

Session Management

Tool	Description
create_session	Create a browser session — provide profileId for an existing profile, or call with no arguments to create a temporary one (all parameters are optional with sensible defaults)
list_sessions	List all active browser sessions
switch_session	Switch the active session
close_session	Close a session and disconnect

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.

Tool	Description
browser_navigate	Navigate to a URL
browser_navigate_back	Go back in browser history
browser_snapshot	Get an accessibility snapshot of the page
browser_take_screenshot	Take a screenshot (PNG or JPEG)
browser_click	Click an element
browser_type	Type text into an editable element
browser_fill_form	Fill multiple form fields at once
browser_press_key	Press a keyboard key
browser_hover	Hover over an element
browser_select_option	Select a dropdown option
browser_drag	Drag and drop between elements
browser_file_upload	Upload files
browser_evaluate	Evaluate JavaScript on page or element
browser_run_code	Run a Playwright code snippet
browser_wait_for	Wait for text, text disappearance, or time
browser_tabs	Manage tabs (list, new, close, select)
browser_console_messages	Read console messages
browser_network_requests	List network requests
browser_resize	Resize the browser window
browser_handle_dialog	Accept or dismiss dialogs

NSTBrowser Management

Tool	Description
nst_get_profiles	List available NSTBrowser profiles
nst_get_browsers	List running NSTBrowser instances

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).

Parameter	Description
profileId	Existing NSTBrowser profile ID to connect to
name	Name for the temporary profile (used when no profileId)
kernel	Browser kernel (chromium)
kernelMilestone	Kernel version milestone (e.g. 128, 130, 132)
platform	Target platform: linux, mac, or windows
headless	Run browser in headless mode
proxy	Proxy string (e.g. http://user:pass@host:port)

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