RoxyBrowser MCP Server

English | 中文

A Model Context Protocol (MCP) server for RoxyBrowser that provides AI assistants with the ability to manage browser instances and obtain Chrome DevTools Protocol (CDP) WebSocket endpoints for automation.

Features

• 🚀 Browser Management: Open and close RoxyBrowser instances programmatically
• 🔗 CDP Integration: Get WebSocket endpoints for Chrome DevTools Protocol automation
• 🤖 AI-Friendly: Seamlessly integrates with AI assistants through MCP
• 🎯 Playwright Ready: Works with RoxyBrowser Playwright MCP (RoxyBrowser's customized Playwright MCP)
• 📊 Workspace Support: Manage browsers across different workspaces and projects
• 🛠️ Browser Creation: Create browsers (single or batch) with full configuration
• 🌐 Proxy Management: List, create, detect, and manage proxy configurations
• 👤 Account Management: Manage platform accounts and credentials in workspaces
• 🔧 Advanced Configuration: Fingerprints, cache clear, random fingerprint, and more
• 🏥 Health Check: Server and workspace connectivity diagnostics

Quick Start

Prerequisites

1. RoxyBrowser installed and running
2. RoxyBrowser API enabled in settings:
   • Open RoxyBrowser → API
   • Set "API Status" to "Enable"
   • Copy your API Key
   • Note the API port (default: 50000)

MCP Client Configuration

Add both RoxyBrowser OpenAPI and RoxyBrowser Playwright MCP to your MCP client configuration:

Claude Desktop / VS Code / Cursor:

{
  "mcpServers": {
    "roxybrowser-openapi": {
      "command": "npx",
      "args": ["@roxybrowser/openapi@latest"],
      "env": {
        "ROXY_API_KEY": "YOUR API KEY",
        "ROXY_API_HOST": "http://127.0.0.1:50000"
      }
    },
    "roxybrowser-playwright-mcp": {
      "command": "npx",
      "args": ["@roxybrowser/playwright-mcp@latest"]
    }
  }
}

Note: Replace YOUR API KEY and YOUR API HOST with your actual RoxyBrowser credentials.

Usage

This package supports three ways to run: CLI, in-process (programmatic), and as a library for custom integration.

1. CLI (direct start)

Start the MCP server from the command line. Ideal for MCP clients that spawn the server as a subprocess.

# After npm install -g @roxybrowser/openapi
roxy-browser-mcp

# Or with npx (no global install)
npx @roxybrowser/openapi

# After cloning and building
npm run build && node lib/index.js

CLI options (config: CLI args > environment variables > defaults):

• -V, --version — Show version
• -h, --help — Show usage
• -H, --api-host <url> — RoxyBrowser API base URL (default: http://127.0.0.1:50000)
• -k, --api-key <key> — API key (required unless set via env)
• -t, --timeout <ms> — Request timeout in milliseconds (default: 30000)

Environment variables (used when an option is not passed): ROXY_API_HOST, ROXY_API_KEY, ROXY_TIMEOUT.

Examples:

roxy-browser-mcp --api-key "your-key"
roxy-browser-mcp -k "your-key" -H http://127.0.0.1:50000
ROXY_API_KEY=your-key roxy-browser-mcp

2. In-process (programmatic start)

Run the MCP server inside your own Node process (same process, stdio transport). Useful when you want to start the server from code instead of a separate CLI process.

import { runServer } from '@roxybrowser/openapi'

// Starts MCP server on stdio; runs until process exits
await runServer()

Or use the server class for more control:

import { RoxyBrowserMCPServer } from '@roxybrowser/openapi'

const server = new RoxyBrowserMCPServer()
await server.run()

Set env vars (ROXY_API_KEY, ROXY_API_HOST) before calling runServer(); config is read at process start and cannot be changed at runtime.

3. Library (secondary development)

Use the exported tools and API helpers in your own app: call RoxyBrowser APIs wi

... View full README on GitHub