NexBrowser MCP Server

English | 简体中文

Connect MCP clients such as Codex, Claude Code, Claude Desktop, and Cursor to NexBrowser Desktop for environment management and browser automation.

NexBrowser Desktop must be running with NexBrowser OpenAPI enabled. This package is an MCP adapter, not a standalone browser.

Quick start

1. Enable NexBrowser OpenAPI

1. Start NexBrowser Desktop.

2. Open API MCP and enable NexBrowser OpenAPI.

3. Copy the displayed API key. The default address is http://127.0.0.1:45536.

Requires Node.js 18 or later; Node.js 20 or later is recommended.

2. Add the MCP server

Replace <your-openapi-token> with the API key from NexBrowser Desktop.

Codex:

codex mcp add nexbrowser \
  --env NEX_API_KEY=<your-openapi-token> \
  --env NEX_API_HOST=http://127.0.0.1:45536 \
  -- npx -y @nexbrowser/mcp@latest

Claude Code:

claude mcp add nexbrowser \
  --env NEX_API_KEY=<your-openapi-token> \
  --env NEX_API_HOST=http://127.0.0.1:45536 \
  -- npx -y @nexbrowser/mcp@latest

Other MCP clients:

{
  "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>"
      }
    }
  }
}

Restart or reload the MCP client after changing its configuration.

3. Install the automation Skill (optional)

The Skill teaches compatible agents how to choose tools, use snapshot references, and recover from common errors.

npx skills add https://github.com/nex-browser/nexbrowser-mcp --skill nexbrowser-automation

Capabilities

• Manage environments: list, open, close, and inspect NexBrowser environments.

• Organize windows: list groups with their window counts, create, rename, and delete groups, and move windows in or out of a group.

• Manage workspace proxies and platform accounts: list, create, update, delete, and detect proxies; list and edit platform-account catalog entries; bind accounts to closed windows. Secrets are never returned.

• Automate pages: connect, navigate, click, type, upload files, and manage tabs.

• Inspect pages: snapshots, screenshots, visible text, console messages, and network requests.

• Isolate sessions: each MCP process owns its browser sessions and active-tab state.

Common tools:

nex_browser_list              nex_browser_open
nex_browser_close             nex_browser_connect
nex_browser_tab_list          nex_browser_snapshot
nex_browser_click             nex_browser_fill_form
nex_browser_take_screenshot   nex_browser_network_requests

The complete tool catalog is available through MCP tools/list. Tool access remains controlled by NexBrowser Desktop.

Configuration

Equivalent CLI flags are --api-key, --api-host, --timeout, and --expose-cdp. Environment variables are safer for secrets because command-line values may be stored in shell history or visible to other local processes.

Troubleshooting

• Connection failed: confirm NexBrowser Desktop is running and OpenAPI is enabled.

• Unauthorized: copy the current API key again and update NEX_API_KEY.

• Not found: update NexBrowser Desktop to a release that provides API MCP and the unified /automation/* endpoints.

• No tools after setup: restart or reload the MCP client.

• Custom port: set NEX_API_HOST to the address displayed by NexBrowser Desktop.

See GitHub Releases for package versions.

Security

• Keep OpenAPI bound to the loopback interface unless remote access is explicitly required.

• Never commit or publish API keys, MCP configuration files containing keys, screenshots, or logs.

• Resetting the API key immediately invalidates the previous key.

• Snapshots, screenshots, page content, console output, and network logs may contain sensitive data and may be sent to the configured model provider.

• Enable page evaluation, code execution, local-file access, or raw CDP URLs only when needed.

NexBrowser Desktop remains responsible for authorization and file-access policy.

Package usage

Run the MCP server directly:

npx -y @nexbrowser/mcp@latest

Or install the CLI globally:

npm install --global @nexbrowser/mcp
nexbrowser-mcp

Embed it in another MCP host:

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);
await server.close();

Development

The repository uses Node.js 24.19.0 and pnpm 11 for development. The published package supports Node.js 18 or later.

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

The real Desktop integration test is disabled by default. Run it only with a dedicated test window and API key:

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