RoxyBrowser MCP Server
OfficialThe RoxyBrowser MCP Server enables programmatic management of RoxyBrowser antidetect browser environments via MCP tools, covering browser lifecycle, proxy, account, workspace, and health operations.
Browser Management
List, create (individually or in batch), open, close, update, delete, and get detailed info for browsers
Open browsers and retrieve CDP WebSocket endpoints and PIDs for automation
Configure OS, user agent, core version, search engine, default URLs, and fingerprinting options (WebGL, Canvas, WebRTC, timezone, geolocation, resolution, device memory, etc.)
Randomize a browser's fingerprint for enhanced anonymity
Clear local or server-side cache for specific browser instances
List labels within a workspace for browser organization
Proxy Management
List, create (individually or in batch), get detail, detect/test, modify, and delete proxy configurations
Supports HTTP, HTTPS, SOCKS5, and SSH proxy types
Platform Account Management
List, create (individually or in batch), modify, and delete platform accounts with credentials (username, password, cookies, EFA, URL, remarks)
Workspace & Health
List all workspaces and their projects
Perform a health check to verify the RoxyBrowser server is running and reachable
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RoxyBrowser MCP Server open a new browser in workspace 1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RoxyBrowser OpenAPI 3.0
RoxyBrowser OpenAPI 3.0 is a breaking rewrite of the MCP and SDK package. It separates the raw RoxyBrowser local API client from the product SDK and MCP preset, so backend endpoint names, SDK operation names, and public MCP tool names are no longer coupled.
Install
pnpm add @roxybrowser/openapiRelated MCP server: @browserview/mcp
CLI Usage
Start the browser MCP server:
roxybrowser-openapi-mcp --api-key "YOUR_API_KEY" --workspace-id 19744Run the published package directly with npx:
npx -y @roxybrowser/openapi --api-key "YOUR_API_KEY" --workspace-id 19744The package exposes a single executable, so npx resolves it automatically. Do not append
roxybrowser-openapi-mcp after the package name.
Use the CLI to inspect available MCP tools and one tool's input schema:
npx -y @roxybrowser/openapi help
npx -y @roxybrowser/openapi help tools
npx -y @roxybrowser/openapi help roxy_profile_create
npx -y @roxybrowser/openapi call roxy_profile_list '{"page":1,"pageSize":20}' --api-key "YOUR_API_KEY" --workspace-id 19744Quick SDK calls are available from the same CLI. Each method argument is parsed as JSON when possible, otherwise it is passed as a string:
npx -y @roxybrowser/openapi sdk profiles.list '{"page":1,"pageSize":20}' \
--api-key "YOUR_API_KEY" --workspace-id 19744
npx -y @roxybrowser/openapi sdk profiles.open profile-1 '{"forceOpen":true}' \
--api-key "YOUR_API_KEY" --workspace-id 19744For a RoxyBrowser endpoint that is not in the SDK yet, call the raw API debugger:
npx -y @roxybrowser/openapi api POST /browser/new_feature '{"dirId":"profile-1"}' \
--api-key "YOUR_API_KEY" --workspace-id 19744Raw GET requests send JSON params as query parameters, and raw POST requests send JSON params
as the request body. The configured workspaceId is injected into object params by default; add
--no-workspace to disable that.
Check the package version and whether an operation exists for a RoxyBrowser app version:
npx -y @roxybrowser/openapi version
npx -y @roxybrowser/openapi supports browser.profile.open 4.0.4Options:
-H, --api-host <url>: RoxyBrowser API base URL. Default:http://127.0.0.1:50000-k, --api-key <key>: RoxyBrowser API key.-w, --workspace-id <id>: optional default workspace ID for SDK and raw API CLI calls. The browser MCP server validates the API key and discovers the active workspace at startup; ordinary MCP tools do not acceptworkspaceId.-t, --timeout <ms>: request timeout. Default:30000
Environment variables are also supported: ROXY_API_HOST, ROXY_API_KEY, ROXY_TIMEOUT, and the optional ROXY_WORKSPACE_ID.
Codex and Claude Code
If you want to add this package as a published MCP server in Codex or Claude Code, point the client at the npm package entry.
Codex:
codex mcp add roxybrowser \
--env ROXY_API_KEY=YOUR_API_KEY \
--env ROXY_API_HOST=http://127.0.0.1:50000 \
--env ROXY_TIMEOUT=30000 \
--env ROXY_WORKSPACE_ID=19744 \
-- npx -y @roxybrowser/openapiClaude Code:
claude mcp add roxybrowser \
-e ROXY_API_KEY=YOUR_API_KEY \
-e ROXY_API_HOST=http://127.0.0.1:50000 \
-e ROXY_TIMEOUT=30000 \
-e ROXY_WORKSPACE_ID=19744 \
-- npx -y @roxybrowser/openapiMCP Inspector 2.0
The repository includes an Inspector 2.0 server configuration for the browser stdio preset. Copy the local environment template and provide your RoxyBrowser credentials before starting the Inspector:
cp .env.example .envROXY_API_KEY=your_api_key_from_roxybrowser
ROXY_API_HOST=http://127.0.0.1:50000
ROXY_TIMEOUT=30000
ROXY_WORKSPACE_ID=19744.env is ignored by Git. The checked-in mcp.inspector.json contains no credentials and starts roxybrowser from the built lib entry.
Start the Web Inspector and select the server from the Servers screen:
pnpm inspectUse the terminal UI instead:
pnpm inspect:tuiRun non-interactive tool-list smoke tests:
pnpm inspect:cli:browserFor a direct CLI call, build first and select a server from the shared configuration:
pnpm build
pnpm exec mcp-inspector --cli --config mcp.inspector.json --server roxybrowser \
--method tools/call --tool-name roxy_workspace_list --tool-args-json '{}'Inspector 2.0 requires Node.js 22.19.0 or newer. The development runtime managed by this repository is Node.js 24.15.0.
SDK Usage
Browser product SDK:
import { RoxyBrowserClient } from "@roxybrowser/openapi";
const roxy = new RoxyBrowserClient({
apiKey: "YOUR_API_KEY",
apiHost: "http://127.0.0.1:50000",
workspaceId: 19744,
});
const profiles = await roxy.profiles.list({
page: 1,
pageSize: 20,
windowName: "Amazon",
});
const opened = await roxy.profiles.open(profiles.rows[0].dirId, { forceOpen: true });Low-level API access is available through RoxyApiClient when endpoint-shaped calls are needed:
import { RoxyApiClient } from "@roxybrowser/openapi";
const api = new RoxyApiClient({ apiKey: "YOUR_API_KEY", workspaceId: 19744 });
const raw = await api.proxy.listMerged({ page_index: 1, page_size: 20 });SDK and MCP capabilities are versioned against the RoxyBrowser app version. The package version is
available as ROXY_OPENAPI_VERSION, while supports() checks a RoxyBrowser app version:
import { RoxyBrowserClient, ROXY_OPENAPI_VERSION } from "@roxybrowser/openapi";
const roxy = new RoxyBrowserClient({
apiKey: "YOUR_API_KEY",
roxyBrowserVersion: "4.0.4",
});
console.log(ROXY_OPENAPI_VERSION);
console.log(roxy.getCapability("browser.profile.open"));
console.log(roxy.supports("browser.profile.open"));Embedded MCP Usage
import { createRoxyBrowserMcpServer } from "@roxybrowser/openapi";
const browserServer = createRoxyBrowserMcpServer({
timeout: 45_000,
roxyBrowserVersion: "4.0.4",
includeTools: ["roxy_profile_list", "roxy_profile_get", "roxy_profile_open"],
roxy: { apiKey: "YOUR_API_KEY", workspaceId: 19744 },
});Public MCP Tool Names
The browser preset exposes 27 tools in profile language. On startup it calls
roxy_workspace_get_active with the configured API key, caches the returned workspace ID, and uses
that ID for workspace-scoped requests. Ordinary MCP tools do not expose a workspaceId argument.
roxy_workspace_select is the exception because it requires the target workspace ID; after a
successful switch it replaces the cached API key, API host, and workspace ID for subsequent calls.
Its result includes the new API key, host, port, OpenAPI status, and API rate limit, and instructs
the caller to use the new credentials because requests with the previous connection will fail.
roxy_workspace_list(RoxyBrowser 4.0.4+; lists all workspaces through/workspace/list)roxy_workspace_list_all(legacy alias; RoxyBrowser 4.0.4+)roxy_workspace_select(RoxyBrowser 4.0.4+)roxy_workspace_get_active(RoxyBrowser 4.0.4+)roxy_project_listroxy_label_listroxy_profile_listroxy_profile_getroxy_profile_createroxy_profile_updateroxy_profile_openroxy_profile_closeroxy_profile_deleteroxy_profile_connection_inforoxy_profile_randomize_fingerprintroxy_profile_clear_local_cacheroxy_profile_clear_server_cacheroxy_proxy_listroxy_proxy_createroxy_proxy_updateroxy_proxy_deleteroxy_proxy_detectroxy_proxy_detect_channelsroxy_platform_account_listroxy_platform_account_createroxy_platform_account_updateroxy_platform_account_delete
Set roxyBrowserVersion to the current RoxyBrowser app version when creating a preset. Tools and
schema fields added after that app version are hidden.
Each MCP tool keeps debug metadata with a stable operationId, the underlying RoxyBrowser endpoint,
the package version, and sinceRoxyBrowserVersion in tool _meta only when that tool has an app
version requirement. Unmarked tools and schema fields are available for all RoxyBrowser app versions.
Create tools accept a resource array. Pass one item to create a single resource, or multiple items to
create a batch. Browser profile, proxy, and platform-account tools use profiles, proxies, and
accounts.
Architecture
The 3.0 source tree is intentionally split:
src/api: raw RoxyBrowser HTTP API client.src/sdk: public SDK clients.src/domains/browser: browser profile, proxy, workspace, and platform account domains.src/mcp/runtime: reusable MCP runtime.src/mcp/presets/browser: browser-mode MCP preset.src/cli: CLI implementation.
See docs/architecture-3.0.md for the full design.
Development
pnpm install
pnpm check
pnpm build
pnpm test
pnpm coverageVite+ manages formatting, linting, type checks, testing, coverage, task execution, and library packaging. pnpm coverage builds the package, runs the 3.0 unit tests, and enforces 90% coverage for lines, branches, and functions across the rewritten API, SDK, domain, and MCP layers.
Available Tools
26 toolsroxy_batch_create_accountsB
Batch create multiple platform accounts
Inputs: workspaceId (required), accountList (required).
roxy_batch_create_browsersB
Create multiple browsers in batch by passing an array of browser configurations
Inputs: browsers (required).
roxy_clear_local_cacheA
Clear local cache for specified browsers
Inputs: dirIds (required).
roxy_clear_server_cacheB
Clear server-side cache for specified browsers
Inputs: workspaceId (required), dirIds (required).
roxy_close_browsersB
Close multiple browsers by their directory IDs
Inputs: dirIds (required).
roxy_create_accountC
Create a new platform account with credentials
Inputs: workspaceId (required), platformUrl (required), platformUserName (required), platformPassword (required), +4 more.
roxy_create_browserB
Create a browser with complete configuration control - for expert users needing full parameter access
Inputs: workspaceId (required), windowName, coreVersion, os, +11 more.
roxy_create_proxiesC
Batch create multiple proxy configurations
Inputs: workspaceId (required), proxyList (required).
roxy_delete_accountsB
Delete one or more platform accounts
Inputs: workspaceId (required), ids (required).
roxy_delete_browsersB
Delete multiple browsers permanently by their directory IDs
Inputs: workspaceId (required), dirIds (required).
roxy_delete_proxiesC
Delete one or more proxy configurations
Inputs: workspaceId (required), ids (required).
roxy_detect_proxyC
Detect/test a proxy configuration and update its IP information
Inputs: workspaceId (required), id (required).
roxy_get_browser_detailC
Get detailed information for a specific browser window
Inputs: workspaceId (required), dirId (required), windowSortNum.
roxy_get_connection_infoA
Get connection information (CDP endpoints, PIDs) for currently opened browsers
Inputs: dirIds.
roxy_health_checkA
Check whether the RoxyBrowser server is running and reachable.
Inputs: no named parameters.
roxy_list_accountsB
Get list of accounts (platform credentials) in specified workspace
Inputs: workspaceId (required), accountId, pageIndex, pageSize.
roxy_list_browsersB
Get list of browsers in specified workspace/project
Inputs: workspaceId (required), projectIds, windowSortNum, windowName, +2 more.
roxy_list_labelsA
Get list of labels in specified workspace
Inputs: workspaceId (required).
roxy_list_proxiesC
Get list of proxy IP List.
Inputs: workspaceId (required), country, checkStatus, startDate, +5 more.
roxy_list_workspacesA
Get list of all workspaces and their projects from RoxyBrowser
Inputs: pageIndex, pageSize.
roxy_modify_accountB
Modify/update an existing platform account
Inputs: workspaceId (required), id (required), platformUrl, platformUserName, +5 more.
roxy_modify_proxyC
Modify/update an existing proxy configuration
Inputs: workspaceId (required), id (required), protocol, host, +7 more.
roxy_open_browsersB
Open one or multiple browsers and return their CDP WebSocket endpoints for automation
Inputs: workspaceId (required), dirIds (required), forceOpen, args.
roxy_proxy_detailB
Get detailed information for a specific proxy configuration
Inputs: workspaceId (required), id (required).
roxy_random_fingerprintC
Randomize browser fingerprint for a specific browser
Inputs: workspaceId (required), dirId (required).
roxy_update_browserB
Update a browser with complete configuration control - for expert users needing full parameter access
Inputs: workspaceId (required), windowName, coreVersion, os, +11 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Tools have distinct purposes, but batch vs individual create operations could cause confusion if descriptions are not read carefully. Overall, each tool targets a specific resource and action.
All tools follow 'roxy_verb_noun' pattern with minor inconsistencies like 'health_check' instead of 'check_health' and 'proxy_detail' lacking 'get_' prefix. Mostly consistent.
26 tools is slightly above the ideal range but each tool serves a clear purpose in browser, account, and proxy management. The scope justifies the count.
Covers CRUD for browsers, accounts, proxies, plus cache, health, and fingerprint. Missing a single-close browser tool and an explicit 'list opened browsers' but overall lifecycle is well-covered.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Zenrows MCP server: Fetch, Extract, Batch, and Browser Sessions for AI agents
MCP server to assist with JxBrowser development.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for browser automation, exposing tools for tab management, navigation, CDP, action plans, and cleanup.1,059 npm421MIT

@browserview/mcpofficial
AlicenseAqualityDmaintenanceMCP server for browserview.io that lets agents create, inspect, share, and destroy disposable cloud Chromium sessions, and connect via CDP using Playwright or Puppeteer.610 npmMIT- AlicenseNot gradedqualityDmaintenanceMCP server for multi-engine browser automation with proxy rotation, enabling AI-driven web interaction and task execution across Camoufox, DrissionPage, and Browser Use.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceA high-performance MCP server for browser automation via Chrome DevTools Protocol, enabling fast, low-cost, and anti-bot web interactions.23 npmMIT