# TgeBrowser MCP Server

[中文文档](./README.zh.md)

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](https://docs.tgebrowser.com/) 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

**Quick Install:**
```bash
git clone https://github.com/你的用户名/tgebrowser-mcp-server.git
cp -r tgebrowser-mcp-server/skills/tgebrowser ~/.config/claude/skills/
```

**Detailed Instructions:**
- [Skills Installation Guide](./SKILLS_INSTALLATION.md) - Multiple installation methods
- [OpenClaw Setup Guide](./OPENCLAW_SETUP.md) - OpenClaw specific configuration

### Using Skills

**For Claude Code / OpenClaw:**

See [OPENCLAW_SETUP.md](./OPENCLAW_SETUP.md) for detailed setup instructions.

Quick setup:
1. Copy or link `skills/tgebrowser` to your AI assistant's skills directory
2. The AI will automatically use intelligent workflows when operating TgeBrowser

**Skills Documentation:**
- [Main Skill Guide](./skills/tgebrowser/SKILL.md) - Complete usage guide
- [Environment Management](./skills/tgebrowser/references/environment-management.md)
- [Fingerprint Config](./skills/tgebrowser/references/fingerprint.md)
- [Proxy Config](./skills/tgebrowser/references/proxy-config.md)

## Available Tools

### Browser Management

| Tool | Description |
|------|-------------|
| `create-browser` | Create a browser environment |
| `update-browser` | Update a browser environment |
| `delete-browser` | Delete a browser environment |
| `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 |
| `get-opened-browser` | List currently opened browser environments |
| `get-browser-active` | Get active browser environment info |
| `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 |
| `delete-cache` | Clear local cache of a browser environment |
| `get-group-list` | List browser groups |
| `get-proxy-list` | List proxies |
| `check-status` | Check TgeBrowser API availability |

### 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 |
| `navigate` | Navigate to a URL |
| `screenshot` | Take a screenshot of the current page |
| `get-page-visible-text` | Get visible text content of the page |
| `get-page-html` | Get HTML content of the page |
| `click-element` | Click an element by CSS selector |
| `fill-input` | Fill an input field |
| `select-option` | Select an option from a dropdown |
| `hover-element` | Hover over an element |
| `scroll-element` | Scroll an element |
| `press-key` | Press a keyboard key |
| `drag-element` | Drag an element to a target |
| `iframe-click-element` | Click an element inside an iframe |
| `evaluate-script` | Execute JavaScript in the browser |


Once connected, you can talk to your AI assistant naturally. Here are some examples:

### Create & manage environments

> Create a Windows environment using Chrome 143 kernel, no proxy

> Batch create 5 browser environments with random fingerprints on Windows

> Rename browser environment ID 12345 to "work-account-01"

> List the 10 most recently opened browser environments

> Delete all environments whose name contains "test"

### Open & automate

> Open environment 12345, navigate to https://example.com, and take a screenshot

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

> Open environment 12345 and get all links on the page

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

### Fingerprint & proxy

> Generate a new random fingerprint for environment 12345

> Check the current User-Agent of environment 12345

> Update the proxy of environment 12345 to socks5://127.0.0.1:1080

### Groups & proxies

> Create a group named "overseas-accounts"

> List all proxies and find those of type socks5

> Move environments 101, 102, 103 to the "overseas-accounts" group

## Development

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

For local development:

```json
{
  "mcpServers": {
    "tgebrowser": {
      "command": "node",
      "args": ["<your-project-path>/tgebrowser/packages/mcp/build/server.js"]
    }
  }
}
```