TgeBrowser MCP Server

English

基于 Model Context Protocol (MCP) 的 TgeBrowser 本地 API 服务端。让 AI 助手能够通过本地 REST API 与 TgeBrowser 交互——创建、管理并自动化浏览器环境。

环境要求

• 已安装并运行 TgeBrowser
• Node.js 18 或更高版本

MCP 服务端配置

Claude Desktop

编辑配置文件：

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

macOS / Linux：

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

Windows：

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

Claude Code

claude mcp add tgebrowser -- npx @tgebrowser/mcp

Cursor

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

配置说明

端口

默认端口为 50326，可通过 --port 参数或 PORT 环境变量覆盖。

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

API Key

通过 --api-key 参数或 API_KEY 环境变量提供，以 Authorization: Bearer 请求头发送。

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

完整示例

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

可用工具

浏览器管理

| 工具 | 说明 | |------|------| | create-browser | 创建浏览器环境（支持自定义指纹、代理、启动配置） | | update-browser | 更新已有浏览器环境（需传 envId 和 browserName） | | delete-browser | 删除单个浏览器环境 | | delete-browser-batch | 批量删除多个浏览器环境 | | open-browser | 打开浏览器环境，返回自动化所需的 WebSocket URL | | close-browser | 关闭指定浏览器环境 | | close-all-profiles | 关闭所有已打开的浏览器环境 | | get-browser-list | 分页获取浏览器环境列表（支持关键词搜索和分组过滤） | | get-opened-browser | 获取当前正在运行的浏览器环境列表 | | get-browser-active | 通过 profileId 或 profileNo 获取活跃环境信息 | | get-profile-cookies | 获取指定浏览器环境的 Cookie | | get-profile-ua | 获取指定浏览器环境的 User-Agent | | new-fingerprint | 为指定环境重新生成随机指纹 | | delete-cache | 清除单个浏览器环境的本地缓存 | | delete-cache-batch | 批量清除多个浏览器环境的本地缓存 | | get-mobile-devices | 获取可用的 Android/iOS 移动设备型号列表 |

分组管理

| 工具 | 说明 | |------|------| | get-group-list | 获取所有浏览器分组列表 | | create-group | 创建新分组 | | update-group | 重命名已有分组 | | delete-group | 删除指定分组 |

代理管理

| 工具 | 说明 | |------|------| | get-proxy-list | 获取所有已保存的代理列表 | | create-proxy | 创建新代理配置（支持 http 和 socks5） | | update-proxy | 更新已有代理配置 | | delete-proxy | 删除指定代理配置 |

窗口管理

| 工具 | 说明 | |------|------| | window-sort | 自动排列所有打开的浏览器窗口以适应屏幕 | | window-sort-custom | 按自定义网格或对角线布局排列窗口 | | window-hide | 隐藏 TgeBrowser 客户端窗口到系统托盘 | | window-show | 显示 TgeBrowser 客户端窗口 |

系统

| 工具 | 说明 | |------|------| | check-status | 检查 TgeBrowser API 可用性与连接状态 |

浏览器自动化

| 工具 | 说明 | |------|------| | connect-browser-with-ws | 通过 WebSocket CDP URL 连接已打开的浏览器 | | open-new-page | 在已连接的浏览器中打开新标签页 | | navigate | 导航到指定 URL | | screenshot | 对当前页面截图（返回图片；savePath 设置保存目录） | | get-page-visible-text | 获取当前页面的可见文本内容 | | get-page-html | 获取当前页面的完整 HTML | | click-element | 通过 CSS 选择器点击元素 | | fill-input | 通过 CSS 选择器填写输入框 | | select-option | 通过值选择下拉菜单选项 | | hover-element | 悬停于指定元素上 | | scroll-element | 将指定元素滚动至可视区域 | | press-key | 按下键盘按键（可选择聚焦到某个选择器） | | drag-element | 将元素拖拽到目标元素位置 | | iframe-click-element | 点击 iframe 内的元素 | | evaluate-script | 在浏览器上下文中执行 JavaScript |

AI 使用指南

AI 如何自动串联工具完成任务

你不需要手动调用工具——用自然语言描述目标，AI 会自动规划并执行完整的工具调用链。

自动化工作流：

get-browser-list  ->  找到 envId/userIndex
open-browser  ->  获取 ws URL
connect-browser-with-ws  ->  建立连接
navigate / click / fill-input / screenshot  ->  完成任务

移动端指纹工作流：

get-mobile-devices  ->  获取设备 id
create-browser 或 update-browser  ->  传入 mobileDeviceId

批量操作工作流：

get-browser-list  ->  收集匹配的 envId
delete-browser-batch 或 delete-cache-batch

代理分配工作流：

create-proxy  ->  获取 proxyId
create-browser 或 update-browser  ->  传入 proxyId

写出更好提示词的技巧

• 名称或 ID 均可：说「名为 work-01 的环境」或「环境 ID 12345」——AI 会自动查找。
• 描述目标而非步骤：说「登录网站并截图首页」——AI 自动处理点击和表单填写。
• 链式任务：说「依次打开 3 个环境，每个都导航到谷歌并截图」——AI 自动循环执行。
• 点击前先获取页面：AI 应先调用 get-page-html 或 get-page-visible-text 确认正确的选择器，再执行点击或填写。
• 指纹参数：os（Windows/macOS/Android/iOS）、kernel（Chrome 版本 133-143）、resolution、language、timezone、webrtc（disable/replace/real）、canvas、ram、cpu。
• 代理参数：protocol（http/socks5）、host、port、username、password，或通过 proxyId 复用已有代理。
• 窗口布局：指定 col（列数）、width、height、startX、startY、spaceX、spaceY 实现精准网格排列。

示例提示词

创建与管理环境

创建一个 Windows 环境，Chrome 135 内核，1920x1080 分辨率，英语，时区 Europe/Amsterdam，不使用代理

批量创建 5 个随机指纹的 Windows 浏览器环境，全部放入名为「工作」的分组

创建一个 iPhone 14 Pro 的 iOS 环境，分配代理 ID 7

把环境 ID 12345 重命名为「主号-01」

列出分组 ID 3 中的所有环境

找出名称包含「测试」的所有环境并批量删除

同时清除环境 101、102、103 的缓存

有哪些 Android 移动设备型号可以用于指纹配置？

打开与自动化

打开环境 12345，导航到 https://example.com，截一张全页截图

打开环境 12345，填写登录表单——用户名 admin，密码 123456——点击登录按钮，然后截图

打开环境 12345，获取页面 HTML，提取所有 href 链接

依次打开环境 101、102、103，每个都导航到 https://example.com 并截图

打开环境 12345，滚动到页面底部，点击「加载更多」按钮

打开环境 12345，在 iframe 搜索框中点击，输入「hello」，然后按 Enter

打开环境 12345，执行脚本获取 document.title

打开环境 12345，悬停在「产品」菜单上，再点击下拉选项「手机」

指纹与代理

为环境 12345 重新生成一个随机指纹

查看环境 12345 当前的 User-Agent 和 Cookie

更新环境 12345 的代理为 socks5://127.0.0.1:1080，用户名 user，密码 pass

创建一个 Android 环境，使用设备 ID 3，Chrome 137 内核，时区 Asia/Tokyo，禁用 WebRTC

更新环境 12345 的内存为 8GB、CPU 4 核，关闭硬件加速

分组与代理管理

创建名为「欧洲账号」的分组，并把环境 201、202、203 移入

将分组 ID 5 重命名为「亚洲账号」

删除分组 ID 9

添加一个新的 http 代理：主机 1.2.3.4，端口 8080，用户名 u，密码 p，IP 检测服务用 ipinfo

列出所有代理，找出类型为 socks5 的

把代理 ID 3 的密码更新为 newpass123

删除代理 ID 10

窗口管理

自动排列所有打开的浏览器窗口以适应屏幕

把环境 101、102、103、104 排成 2 列网格，每个窗口 900x600，从坐标 (0,0) 开始，间距 10px

把 TgeBrowser 客户端窗口隐藏到托盘，我要专注工作

重新显示 TgeBrowser 客户端窗口

开发

git clone https://github.com/tgebrowser/tgebrowser.git
cd tgebrowser
pnpm install
pnpm run build

本地开发配置：

{
  "mcpServers": {
    "tgebrowser-mcp": {
      "command": "node",
      "args": ["YOUR_PROJECT_PATH/tgebrowser/packages/mcp/build/server.js"]
    }
  }
}