Tgebrowser

TgeBrowser MCP Operations

Use MCP tools to operate TgeBrowser environments, groups, proxies, and browser automation via the mcp__tgebrowser__* tools.

When to Use This Skill

Apply when the user:

• Asks to create, update, delete, or list TgeBrowser environments
• Mentions opening or closing browsers/profiles, fingerprint, UA, or proxy
• Wants to manage groups, proxies, or check API status
• Needs browser automation (navigate, click, fill forms, screenshot, etc.)
• Refers to TgeBrowser or tgebrowser operations

Ensure TgeBrowser is running (default port 50326). The MCP server connects to the TgeBrowser Local API.

Smart Defaults & Best Practices

When creating browsers:

• Always use {"protocol": "direct"} for proxy if user doesn't specify one
• Default fingerprint OS to "Windows" if not specified
• Set webrtc: "disabled" by default for better privacy
• Use clearCacheOnStart: true for clean sessions

When opening browsers:

• Use args: ["--headless"] for automation tasks unless user needs to see the browser
• Let the system auto-assign port unless user specifies one

When automating:

• Always call mcp__tgebrowser__open-browser first and extract the ws URL from response
• Then call mcp__tgebrowser__connect-browser-with-ws with that ws URL
• After connection, you can use navigation and interaction tools

Error handling:

• If browser open fails, check if TgeBrowser app is running via mcp__tgebrowser__check-status
• If envId not found, list browsers first with mcp__tgebrowser__get-browser-list
• Before deleting cache, always close the browser first

Common Workflows

Quick Start: Create and Use a Browser

1. Create: mcp__tgebrowser__create-browser with minimal params (name + proxy)
2. Open: mcp__tgebrowser__open-browser with returned envId
3. Connect: mcp__tgebrowser__connect-browser-with-ws with ws URL from step 2
4. Automate: Use navigation/interaction tools
5. Close: mcp__tgebrowser__close-browser when done

Find and Open Existing Browser

1. List: mcp__tgebrowser__get-browser-list with keyword if needed
2. Open: Use envId from list
3. Connect and automate

Batch Operations

• Use mcp__tgebrowser__get-browser-list to get all browsers
• Iterate through list for batch operations
• Use mcp__tgebrowser__close-all-profiles to close all at once

Essential MCP Tools

Browser Lifecycle (Most Common)

Create a browser:

mcp__tgebrowser__create-browser
Required: {"browserName": "MyBrowser", "proxy": {"protocol": "direct"}}
Smart defaults applied: Windows OS, disabled WebRTC, clean cache on start

Open a browser:

mcp__tgebrowser__open-browser
Required: {"envId": 123} OR {"userIndex": 1}
Returns: ws URL for automation - save this!

Connect for automation:

mcp__tgebrowser__connect-browser-with-ws
Required: {"wsUrl": "ws://127.0.0.1:xxxxx/devtools/browser/..."}
Use ws URL from open-browser response

Close a browser:

mcp__tgebrowser__close-browser
Required: {"envId": 123} OR {"userIndex": 1}

Browser Management

List browsers:

mcp__tgebrowser__get-browser-list
Optional: {"keyword": "search term", "pageSize": 50}
Use this to find envId when you don't know it

Update browser:

mcp__tgebrowser__update-browser
Required: {"envId": 123, "browserName": "NewName"}
Optional: proxy, fingerprint, groupId, remark

Delete browser:

mcp__tgebrowser__delete-browser
Required: {"envId": 123} OR {"userIndex": 1}
Close it first if it's open

Get opened browsers:

mcp__tgebrowser__get-opened-browser
No parameters needed
Returns list of currently running browsers

Browser Automation (After Connection)

Navigate:

mcp__tgebrowser__navigate
Required: {"url": "https://example.com"}

Take screenshot:

mcp__tgebrowser__screenshot
Optional: {"savePath": "./screenshot.png", "isFullPage": true}
Defaults to full page screenshot

Get page content:

mcp__tgebrowser__get-page-visible-text - Get readable text
mcp__tgebrowser__get-page-html - Get full HTML
No parameters needed

Interact with elements:

mcp__tgebrowser__click-element {"selector": "#button"}
mcp__tgebrowser__fill-input {"selector": "#email", "text": "user@example.com"}
mcp__tgebrowser__select-option {"selector": "#country", "value": "US"}
mcp__tgebrowser__hover-element {"selector": ".menu"}
mcp__tgebrowser__scroll-element {"selector": "#footer"}
mcp__tgebrowser__press-key {"key": "Enter"}

Execute JavaScript:

mcp__tgebrowser__evaluate-script
Required: {"script": "return document.title"}
Returns script result

Utility Tools

Get cookies:

mcp__tgebrowser__get-profile-cookies
Required: {"envId": 123}

Get User-Agent:

mcp__tgebrowser__get-profile-ua
Required: {"envId": 123}

Generate new fingerprint:

mcp__tgebrowser__new-fingerprint
Required: {"envId": 123}
Browser must be closed

Clear cache:

mcp__tgebrowser__delete-cache
Required: {"envId": 123}
Browser must be closed

Close all browsers:

mcp__tgebrowser__close-all-profiles
No parameters needed
Emergency stop for all browsers

Check system status:

mcp__tgebrowser__check-status
No parameters needed
Verify TgeBrowser app is running

Groups & Proxies

List groups:

mcp__tgebrowser__get-group-list
Optional: {"pageSize": 50}

List proxies:

mcp__tgebrowser__get-proxy-list
Optional: {"pageSize": 50}

Intelligent Automation Guide

Auto-detect and Handle Common Scenarios

Scenario 1: User wants to automate a website

1. Check if any browser is open: mcp__tgebrowser__get-opened-browser
2. If none, create one with smart defaults: {"browserName": "Auto-Browser", "proxy": {"protocol": "direct"}, "fingerprint": {"os": "Windows", "webrtc": "disabled"}}
3. Open it with headless mode: {"envId": <returned_id>, "args": ["--headless"]}
4. Connect using ws URL from response
5. Navigate and automate

Scenario 2: User mentions a website but no browser specified

• Automatically create a temporary browser with optimal settings
• Use descriptive name like "Temp-{website_domain}"
• Clean up after task completion

Scenario 3: User wants to "open browser" without details

• List existing browsers first
• If found, use the most recently created one
• If none exist, create one with defaults
• Always prefer reusing existing browsers over creating new ones

Scenario 4: Automation fails

• Check connection status first
• Verify browser is still open: mcp__tgebrowser__get-opened-browser
• If closed, reopen and reconnect automatically
• Retry the failed operation once

Scenario 5: User wants to "close everything"

• Use mcp__tgebrowser__close-all-profiles - one command closes all

Smart Parameter Inference

When envId is missing:

• List browsers and use the first/only one if count = 1
• If multiple, ask user or use most recent

When proxy is not specified:

• Always default to {"protocol": "direct"} (no proxy)
• Never leave proxy undefined

When fingerprint is not specified:

• Use safe defaults: {"os": "Windows", "webrtc": "disabled", "clearCacheOnStart": true}

When selector fails:

• Try common alternatives (id, class, name, xpath)
• Wait a few seconds and retry
• Get page HTML to help debug

When screenshot path not specified:

• Auto-generate: ./screenshots/{timestamp}_{envId}.png
• Create directory if needed

Proactive Error Prevention

Before opening browser:

• Verify TgeBrowser is running: mcp__tgebrowser__check-status
• If not running, inform user to start TgeBrowser app

Before deleting/clearing cache:

• Check if browser is open: mcp__tgebrowser__get-opened-browser
• If open, close it first automatically

Before creating browser:

• Validate proxy format if provided
• Ensure browserName is not empty
• Check if name already exists (list first)

Before automation:

• Ensure browser is connected
• Verify page is loaded (check URL or title)
• Wait for elements before interacting

Batch Operations Intelligence

When user wants to operate on multiple browsers:

1. Get full list: mcp__tgebrowser__get-browser-list {"pageSize": 100}
2. Filter by keyword if user mentioned specific criteria
3. Process in parallel when possible (open, close, update)
4. Report progress and errors clearly

When user wants to clean up:

1. Close all: mcp__tgebrowser__close-all-profiles
2. List all: mcp__tgebrowser__get-browser-list
3. Delete unwanted ones based on criteria (name pattern, age, etc.)

Context Awareness

Remember across operations:

• Last opened browser envId
• Last used ws URL
• Current page URL after navigation
• Recently created browsers

Infer user intent:

• "Open browser" → open existing or create new
• "Go to website" → navigate if connected, or open→connect→navigate
• "Click button" → find best selector automatically
• "Get data" → extract visible text or specific elements
• "Take screenshot" → full page by default
• "Close" → close current browser or all if multiple mentioned

All parameter names are camelCase in JSON objects passed to MCP tools.

Environment Management

See references/environment-management.md for mcp__tgebrowser__open-browser, mcp__tgebrowser__close-browser, mcp__tgebrowser__create-browser, mcp__tgebrowser__update-browser, mcp__tgebrowser__delete-browser, mcp__tgebrowser__get-browser-list, mcp__tgebrowser__get-opened-browser, mcp__tgebrowser__get-profile-cookies, mcp__tgebrowser__get-profile-ua, mcp__tgebrowser__close-all-profiles, mcp__tgebrowser__new-fingerprint, mcp__tgebrowser__delete-cache, mcp__tgebrowser__get-browser-active and their parameters.

Group Management

See references/group.md for mcp__tgebrowser__get-group-list parameters.

System

See references/system.md for mcp__tgebrowser__check-status parameters.

Proxy Management

See references/proxy.md for mcp__tgebrowser__get-proxy-list parameters.

Proxy Config (proxy field for create-browser / update-browser)

See references/proxy-config.md for all fields (protocol, host, port, username, password, etc.) and example.

Fingerprint Config (fingerprint field for create-browser / update-browser)

See references/fingerprint.md for all fields (os, kernel, timezone, language, webrtc, TLS, etc.) and example.

Browser Automation

Browser automation tools (navigate, click-element, fill-input, screenshot, etc.) are fully supported via MCP. These tools require an active browser connection established via mcp__tgebrowser__open-browser or mcp__tgebrowser__connect-browser-with-ws.

Deep-Dive Documentation

Reference docs with full enum values and field lists:

Use these when you need the exact allowed values or semantics; the main skill text above only summarizes.