NexBrowser MCP Server

English | 简体中文

Connect an MCP client such as Claude Desktop or Cursor to a running NexBrowser desktop app. This package speaks the Model Context Protocol over stdio and forwards approved tool calls to the app's authenticated local OpenAPI service.

This package is an MCP adapter, not a standalone browser runtime. NexBrowser Desktop must be running and its OpenAPI service must be enabled before a client can use these tools.

What it provides

• Environment management: list, open, close, and inspect NexBrowser environments.
• Browser automation: connect to an environment, inspect pages, take snapshots and screenshots, interact with elements, and inspect console or network activity.
• Session isolation: each MCP process has its own X-Nex-MCP-Client identifier, so browser sessions and active-tab state do not leak between MCP clients.

The Electron main process remains the authority for Playwright/CDP handles and for policy-gated operations such as page evaluation.

Prerequisites

1. Download and start NexBrowser Desktop.
2. Enable NexBrowser OpenAPI and obtain an OpenAPI token.
3. Use Node.js 18 or later in the MCP client environment. Node.js 20 or later is recommended because Node.js 18 has reached end of life.

See version compatibility before pinning this package in a managed deployment.

Never put a real OpenAPI token in a repository, shared configuration, or issue report.

Enable NexBrowser OpenAPI

1. Open API MCP from the NexBrowser Desktop navigation.
2. Turn on Local OpenAPI. The service listens on 127.0.0.1; its default port is 45536.
3. Copy the displayed API key and set it as NEX_API_KEY in the MCP client configuration.
4. If you change the port, update NEX_API_HOST to match the displayed access address.

Keep the service on the loopback interface. Resetting the API key immediately invalidates the old key, so update every authorized MCP client after a reset.

Version compatibility

Component	Supported version
NexBrowser MCP	1.x (releases)
NexBrowser Desktop	Current release containing API MCP and the unified /ai/browser/* endpoints
Node.js runtime	>=18; Node.js 20 or later recommended

If an automation tool returns Not found, first update NexBrowser Desktop. MCP minor releases may add tools without removing existing 1.x tool names; incompatible public API changes require a new MCP major version.

Install

No installation is needed when your MCP client launches the server through npx:

npx -y @nexbrowser/mcp

To get a global nexbrowser-mcp command instead:

npm install --global @nexbrowser/mcp

Configure an MCP client

Add the following server entry to your MCP client's configuration. Replace the token with one generated by the locally running NexBrowser app.

{
  "mcpServers": {
    "nexbrowser": {
      "command": "npx",
      "args": ["-y", "@nexbrowser/mcp@latest"],
      "env": {
        "NEX_API_HOST": "http://127.0.0.1:45536",
        "NEX_API_KEY": "<your-openapi-token>"
      }
    }
  }
}

If the package is installed globally, set "command": "nexbrowser-mcp" and drop args.

Variable	Required	Default	Description
NEX_API_HOST	No	http://127.0.0.1:45536	NexBrowser local OpenAPI base URL.
NEX_API_KEY	Yes	—	Token issued by NexBrowser OpenAPI.
NEX_TIMEOUT	No	30000	HTTP request timeout in milliseconds.
NEX_EXPOSE_CDP	No	disabled	Set to 1 only to return raw CDP endpoints.

The same settings are also available as CLI flags — --api-host (-H), --api-key (-k), --timeout (-t), and --expose-cdp. Flags take precedence over environment variables. The CLI does not load .env from its current directory; pass trusted environment variables through the MCP client configuration.

Prefer NEX_API_KEY over --api-key: command-line secrets may be retained in shell history or visible to other local processes.

Available tools

The complete catalog is advertised through MCP tools/list. Common tools include:

• nex_list_browsers, nex_open_browsers, nex_get_connection_info
• nex_browser_connect, browser_tab_list, browser_snapshot
• browser_click, browser_fill_form, browser_wait_for
• browser_take_screenshot, browser_console_messages, browser_network_requests
• nex_list_ip_products, nex_quote_ip_order, nex_confirm_ip_order, nex_get_ip_order_status

nex_browser_connect requires windowId. Its teamId is optional: when omitted, the NexBrowser Desktop app uses its currently selected team. Existing callers may continue to pass an explicit teamId; the Desktop app validates it against the currently active team.

Tool availability and sensitive capabilities are ultimately controlled by the running NexBrowser Desktop app.

Skill package

The npm package also contains skills/nexbrowser-automation, which teaches compatible agents how to select tools, use short-lived snapshot references, and recover from common errors. MCP does not install skills automatically; install or copy that directory through your agent's normal skill mechanism when skill support is available.

Purchases require a human

The IP purchase tools can start a real, paid order. They cannot complete one.

nex_confirm_ip_order opens a payment confirmation dialog in the NexBrowser desktop app and returns immediately; the charge only happens after a real person clicks Approve there. This server never receives a credential that can bill the account directly, and no MCP host, prompt, or tool argument can approve on the user's behalf. Any confirmation UI an MCP host shows is informational only — it is not what authorizes the payment. If the NexBrowser desktop app is not running and signed in, purchases fail rather than proceeding.

Privacy and security

MCP tool results are visible to the configured MCP client and may be sent to its model provider. Browser snapshots, screenshots, console output, network diagnostics, page content, and optional CDP connection information can contain sensitive data. CDP endpoints are redacted unless the operator sets NEX_EXPOSE_CDP=1 or passes --expose-cdp. Use trusted clients and models, avoid sharing transcripts publicly, and enable browser_evaluate, browser_run_code, and local-file access only when needed. The NexBrowser Desktop app remains responsible for authorization and file-policy enforcement.

Do not pass API keys on the command line in shared environments. Keep the OpenAPI service bound to a trusted interface and use a narrowly scoped token where the Desktop app supports it.

Use as a library

Embed the server in a host process by supplying any MCP SDK transport:

import { NexBrowserMcpServer } from '@nexbrowser/mcp';

const server = new NexBrowserMcpServer({
  apiHost: 'http://127.0.0.1:45536',
  apiKey: process.env.NEX_API_KEY ?? '',
  timeout: 30_000
});

await server.connect(transport);
// Close the server when the host shuts down.
await server.close();

Development

Repository development uses Node.js 24.19.0 (see .nvmrc). Node.js 22.13 or later also works, because that is the minimum required by the pinned pnpm 11 toolchain. The published package has a lower Node.js 18 runtime floor.

pnpm typecheck
pnpm test
pnpm build
pnpm test:package
pnpm inspect

An optional core Desktop E2E is disabled by default. It performs connect → snapshot → zero-distance scroll → disconnect against the supplied test window. Run it only against a test workspace with a dedicated token and window:

NEX_E2E_ENABLED=1 NEX_E2E_WINDOW_ID=your-test-window NEX_API_KEY=your-test-key pnpm test:integration

test runs the Vitest suite directly against the TypeScript source. build bundles the package, emits ESM and CommonJS declarations into lib/, and test:package additionally checks the built ESM, CommonJS, CLI, npm package metadata, and consumer type resolution. inspect builds the package and opens the MCP Inspector against the built CLI (lib/cli.js).