TgeBrowser MCP Server

中文文档

A Model Context Protocol (MCP) server for the TgeBrowser Local API. Enables AI assistants to interact with TgeBrowser — creating, managing, and automating browser environments via the local REST API.

Requirements

TgeBrowser installed and running
Node.js 18 or higher

MCP Server Setup

Claude Desktop

Edit the config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

macOS / Linux:

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "npx",
      "args": ["@tgebrowser/mcp@latest"]
    }
  }
}

Windows:

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "cmd",
      "args": ["/c", "npx", "@tgebrowser/mcp@latest"]
    }
  }
}

Claude Code

bash

claude mcp add tgebrowser -- npx @tgebrowser/mcp@latest

Cursor

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "npx",
      "args": ["@tgebrowser/mcp@latest"]
    }
  }
}

Configuration

Port

Default port is 50326. Override via --port arg or PORT env var.

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "npx",
      "args": ["@tgebrowser/mcp@latest", "--port", "50326"]
    }
  }
}

API Key

Provide via --api-key arg or API_KEY env var. Sent as Authorization: Bearer header.

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "npx",
      "args": ["@tgebrowser/mcp@latest", "--api-key", "your-api-key"]
    }
  }
}

Combined Example

json

{
  "mcpServers": {
    "tgebrowser": {
      "command": "npx",
      "args": ["@tgebrowser/mcp@latest", "--port", "50326", "--api-key", "your-api-key"]
    }
  }
}

Skills Support

This project includes intelligent Skills for AI assistants to operate TgeBrowser more efficiently.

What are Skills?

Skills provide AI assistants with:

Smart defaults (auto-fill missing parameters)
Error prevention (check status before operations)
Intent inference (understand what user wants)
Workflow optimization (automate multi-step processes)

Installation

Download from the GitHub repository and copy the skills/tgebrowser directory to your AI assistant's skills directory:

bash

git clone https://github.com/tuguang2025/tgebrowser-mcp-server
cp -r tgebrowser-mcp-server/skills/tgebrowser ~/.config/claude/skills/

Using Skills

Once installed, the AI will automatically use intelligent workflows when operating TgeBrowser — no additional configuration needed.

Available Tools

Browser Management

Tool	Description
`create-browser`	Create a browser environment (supports custom fingerprint, proxy, startup config)
`update-browser`	Update a browser environment (requires `envId` and `browserName`)
`delete-browser`	Delete a single browser environment
`delete-browser-batch`	Delete multiple browser environments in batch
`open-browser`	Open a browser environment, returns WebSocket URL for automation
`close-browser`	Close a browser environment
`close-all-profiles`	Close all opened browser environments
`get-browser-list`	List browser environments with pagination (supports keyword search and group filter)
`get-opened-browser`	List currently opened browser environments
`get-browser-active`	Get active browser environment info by profileId or profileNo
`get-profile-cookies`	Get cookies of a browser environment
`get-profile-ua`	Get User-Agent of a browser environment
`new-fingerprint`	Generate a new random fingerprint for an environment
`delete-cache`	Clear local cache of a single browser environment
`delete-cache-batch`	Clear local cache of multiple browser environments in batch
`get-mobile-devices`	Get list of available Android/iOS mobile device models

Group Management

Tool	Description
`get-group-list`	List all browser groups
`create-group`	Create a new group
`update-group`	Rename an existing group
`delete-group`	Delete a group

Proxy Management

Tool	Description
`get-proxy-list`	List all saved proxies
`create-proxy`	Create a new proxy configuration (supports http and socks5)
`update-proxy`	Update an existing proxy configuration
`delete-proxy`	Delete a proxy configuration

Window Management

Tool	Description
`window-sort`	Auto-arrange all open browser windows to fit the screen
`window-sort-custom`	Arrange windows in a custom grid or diagonal layout
`window-hide`	Hide the TgeBrowser client window to the system tray
`window-show`	Show the TgeBrowser client window

System

Tool	Description
`check-status`	Check TgeBrowser API availability and connection status

Browser Automation

After calling open-browser, use connect-browser-with-ws with the returned ws URL to enable automation.

Tool	Description
`connect-browser-with-ws`	Connect to an opened browser via WebSocket CDP URL
`open-new-page`	Open a new tab in the connected browser
`navigate`	Navigate to a URL
`screenshot`	Take a screenshot of the current page (`savePath` sets save directory)
`get-page-visible-text`	Get visible text content of the page
`get-page-html`	Get full HTML content of the page
`click-element`	Click an element by CSS selector
`fill-input`	Fill an input field by CSS selector
`select-option`	Select an option from a dropdown by value
`hover-element`	Hover over an element
`scroll-element`	Scroll an element into view
`press-key`	Press a keyboard key (optionally focus a selector first)
`drag-element`	Drag an element to a target element
`iframe-click-element`	Click an element inside an iframe
`evaluate-script`	Execute JavaScript in the browser context

AI Usage Guide

How AI chains tools automatically

You don't need to call tools manually — describe your goal in natural language and the AI will plan and execute the full tool chain.

Automation workflow:

get-browser-list  ->  find envId/userIndex
open-browser  ->  get ws URL
connect-browser-with-ws  ->  establish connection
navigate / click / fill-input / screenshot  ->  complete task

Mobile fingerprint workflow:

get-mobile-devices  ->  get device id
create-browser or update-browser  ->  pass mobileDeviceId

Batch operation workflow:

get-browser-list  ->  collect matching envIds
delete-browser-batch or delete-cache-batch

Proxy assignment workflow:

create-proxy  ->  get proxyId
create-browser or update-browser  ->  pass proxyId

Tips for better prompts

Name or ID both work: Say "the environment named work-01" or "environment ID 12345" — the AI will look it up.
Describe goals, not steps: Say "log in to the site and screenshot the homepage" — the AI handles clicks and form filling.
Chain tasks: Say "open 3 environments in sequence, navigate each to Google and take a screenshot" — the AI loops automatically.
Get page before clicking: The AI should call get-page-html or get-page-visible-text first to confirm the correct selector before clicking or filling.
Fingerprint params: os (Windows/macOS/Android/iOS), kernel (Chrome version 133–143), resolution, language, timezone, webrtc (disable/replace/real), canvas, ram, cpu.
Proxy params: protocol (http/socks5), host, port, username, password, or reuse an existing proxy via proxyId.
Window layout: Specify col, width, height, startX, startY, spaceX, spaceY for precise grid arrangement.

Example Prompts

Create & manage environments

Create a Windows environment using Chrome 135 kernel, 1920x1080 resolution, English, timezone Europe/Amsterdam, no proxy

Batch create 5 browser environments with random fingerprints on Windows, all placed in the group named "work"

Create an iOS environment for iPhone 14 Pro, assign proxy ID 7

Rename environment ID 12345 to "main-account-01"

List all environments in group ID 3

Find all environments whose name contains "test" and delete them in batch

Clear cache for environments 101, 102, 103 simultaneously

What Android mobile device models are available for fingerprint configuration?

Open & automate

Open environment 12345, navigate to https://example.com, take a full-page screenshot

Open environment 12345, fill in the login form with username admin and password 123456, click the login button, then take a screenshot

Open environment 12345, get the page HTML, extract all href links

Open environments 101, 102, 103 in sequence, navigate each to https://example.com and take a screenshot

Open environment 12345, scroll to the bottom of the page, click the "Load More" button

Open environment 12345, click in the iframe search box, type "hello", then press Enter

Open environment 12345, execute a script to get document.title

Open environment 12345, hover over the "Products" menu, then click the "Phones" dropdown option

Fingerprint & proxy

Generate a new random fingerprint for environment 12345

Check the current User-Agent and Cookie of environment 12345

Update the proxy of environment 12345 to socks5://127.0.0.1:1080, username user, password pass

Create an Android environment using device ID 3, Chrome 137 kernel, timezone Asia/Tokyo, disable WebRTC

Update environment 12345 to 8GB RAM, 4 CPU cores, disable hardware acceleration

Groups & proxy management

Create a group named "europe-accounts" and move environments 201, 202, 203 into it

Rename group ID 5 to "asia-accounts"

Delete group ID 9

Add a new http proxy: host 1.2.3.4, port 8080, username u, password p, IP checker ipinfo

List all proxies and find those of type socks5

Update the password of proxy ID 3 to newpass123

Delete proxy ID 10

Window management

Auto-arrange all open browser windows to fit the screen

Arrange environments 101, 102, 103, 104 in a 2-column grid, each window 900x600, starting at (0,0) with 10px spacing

Hide the TgeBrowser client window to the tray so I can focus

Show the TgeBrowser client window again

TgeBrowser MCP Server ​

Requirements ​

MCP Server Setup ​

Claude Desktop ​

Claude Code ​

Cursor ​

Configuration ​

Port ​

API Key ​

Combined Example ​

Skills Support ​

What are Skills? ​

Installation ​

Using Skills ​

Available Tools ​

Browser Management ​

Group Management ​

Proxy Management ​

Window Management ​

System ​

Browser Automation ​

AI Usage Guide ​

How AI chains tools automatically ​

Tips for better prompts ​

Example Prompts ​

Create & manage environments ​

Open & automate ​

Fingerprint & proxy ​

Groups & proxy management ​

Window management ​

TgeBrowser MCP Server

Requirements

MCP Server Setup

Claude Desktop

Claude Code

Cursor

Configuration

Port

API Key

Combined Example

Skills Support

What are Skills?

Installation

Using Skills

Available Tools

Browser Management

Group Management

Proxy Management

Window Management

System

Browser Automation

AI Usage Guide

How AI chains tools automatically

Tips for better prompts

Example Prompts

Create & manage environments

Open & automate

Fingerprint & proxy

Groups & proxy management

Window management