ZennoBrowser MCP Server README

ZennoBrowser MCP Server — Antidetect Browser Automation for AI Agents

MCP (Model Context Protocol) server for ZennoBrowser Public API. Exposes browser automation and profile management capabilities to AI agents such as Claude Desktop, Cursor, and VS Code MCP clients.

Why ZennoBrowser MCP Server

• Full Public API coverage. 57 tools for workspaces, profiles, folders, proxies, threads, browser instances, presets, extensions and product info.
• Built for scale. Bulk tools create, update, start and stop many profiles, proxies, threads and browser instances in one call.
• Cookies and fingerprints. Import, export and copy cookies between profiles, and read full fingerprint details of any profile.
• Works with your AI client. Runs as a local stdio server in Claude Desktop, Cursor and VS Code.
• Free to start. ZennoBrowser is available for Windows. Its START plan includes unlimited local profiles and 2 simultaneous browsers.

Quick start

1. Start ZennoBrowser on your computer and get an API token in your personal account on ZennoLab.
2. Add the server to your MCP client using one of the configurations in Installation.
3. Ask your agent, for example: "Create a new profile named "Test Profile", then start a browser instance for it."

Tools such as delete_profile, bulk_delete_profile and delete_proxy cannot be undone. Review the agent's actions before approving destructive calls.

Requirements

• Node.js 20+
• ZennoBrowser running locally
• A valid ZennoBrowser API token

Installation

The package is published as @zennolab/zennobrowser-mcp-server. Versions up to 1.0.0 were published as the unscoped zennobrowser-mcp-server, which no longer receives updates — replace it with @zennolab/zennobrowser-mcp-server in your MCP client config.

npx (no install required)

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "zennobrowser": {
      "command": "npx",
      "args": ["-y", "@zennolab/zennobrowser-mcp-server@latest"],
      "env": {
        "ZB_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Cursor — add to MCP settings (.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "zennobrowser": {
      "command": "npx",
      "args": ["-y", "@zennolab/zennobrowser-mcp-server@latest"],
      "env": {
        "ZB_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

VS Code (with GitHub Copilot MCP support) — add to .vscode/mcp.json:

{
  "servers": {
    "zennobrowser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zennolab/zennobrowser-mcp-server@latest"],
      "env": {
        "ZB_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Global install

npm install -g @zennolab/zennobrowser-mcp-server@latest

Then use zennobrowser-mcp-server as the command instead of npx ... @zennolab/zennobrowser-mcp-server:

{
  "mcpServers": {
    "zennobrowser": {
      "command": "zennobrowser-mcp-server",
      "env": {
        "ZB_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Environment Variables

Tools

Workspaces

Profiles

Profile Folders

Proxies

Proxy Folders

Threads

Browser Instances

Presets & Extensions

Product

Example Prompts

Create a profile and start the browser:

Create a new profile named "Test Profile", then start a browser instance for it.

Full end-to-end flow:

Create a profile named "Scraper", create a proxy with URI "socks5://user:pass@1.2.3.4:1080", assign the proxy to the profile, create a thread, then start a browser instance for the profile using that thread.

Bulk operations:

List all profiles in my default workspace and delete any that haven't been used in the last 30 days.

Cookie management:

Export cookies from profile "Session A" and import them into profile "Session B".

Troubleshooting

Error: Missing required environment variable ZB_API_TOKEN Set the ZB_API_TOKEN environment variable to your ZennoBrowser API token.

Error: connect ECONNREFUSED 127.0.0.1:8160 ZennoBrowser is not running or the Public API is not working. If the API runs on a different port, set ZB_API_BASE_URL=http://localhost:<port>.

Tool calls return errors with "Unauthenticated" Your API token is invalid or expired. Generate a new token in personal account on ZennoLab.

npx downloads the package every time Install globally with npm install -g @zennolab/zennobrowser-mcp-server@latest to avoid re-downloading on each start.

Related

• ZennoBrowser — the antidetect browser this server controls
• ZennoLab documentation — product guides (in Russian)
• ZennoBrowser community forum — questions, bug reports and feature requests
• zennoposter-mcp — MCP servers for ZennoPoster and ZennoDroid

License

MIT