Content
# Tool List
Шаблон MCP сервера для автоматизации браузера. Работает с любой LLM, поддерживающей MCP (Claude, GPT, Gemini, Mistral и др.).
## Capabilities
| Function | Description |
|---------|----------|
| **Stealth Mode** | Anti-detection through puppeteer-extra-plugin-stealth |
| **Auto-profile** | Automatic search for a profile with cookies |
| **Connection** | Connecting to an already launched browser |
| **16 evasions** | Masking as a regular browser |
### Stealth Mode (protection from captchas)
The server uses `puppeteer-extra-plugin-stealth` to bypass automation checks:
- Hides `navigator.webdriver`
- Adds `chrome.runtime`
- Emulates plugins, languages, permissions
- Masks User-Agent
- And much more
```javascript
// Check stealth mode
browser_check_stealth()
// Test on bot.sannysoft.com
browser_navigate({ url: "https://bot.sannysoft.com/" })
```
## Supported Browsers
| Browser | Status | Note |
|---------|--------|------------|
| Google Chrome | ✅ | Recommended |
| Chromium | ✅ | |
| Microsoft Edge | ✅ | |
| Brave | ✅ | |
| Opera | ✅ | |
| Firefox | ⚠️ | Basic support |
Automatically finds the installed browser. Priority: Chrome > Chromium > Edge > Brave > Opera > Firefox.
## Installation
```bash
cd /root/browser-mcp-template
npm install
# Install Chrome/Chromium (if needed)
npx puppeteer browsers install chrome
```
### Specify a specific browser
Through environment variable:
```bash
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/firefox"
```
## Usage
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/root/browser-mcp-template/index.js"]
}
}
}
```
### Claude Code (CLI)
```bash
claude mcp add browser node /root/browser-mcp-template/index.js
```
### Cursor / Windsurf / VS Code
Add to MCP settings:
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/path/to/browser-mcp-template/index.js"]
}
}
}
```
## Available Tools
### Navigation and Control
| Tool | Description |
|------------|----------|
| `browser_navigate` | Open URL (with browser and profile selection) |
| `browser_click` | Click on an element |
| `browser_type` | Enter text into a field |
| `browser_screenshot` | Take a screenshot |
| `browser_get_text` | Get element text |
| `browser_get_html` | Get element HTML |
| `browser_evaluate` | Execute JavaScript |
| `browser_wait` | Wait for an element or time |
| `browser_select` | Select an option in a dropdown |
| `browser_scroll` | Scroll the page |
| `browser_hover` | Hover over an element |
| `browser_upload` | Upload a file |
| `browser_press` | Press a key |
### Tabs and Information
| Tool | Description |
|------------|----------|
| `browser_list_tabs` | List open tabs |
| `browser_switch_tab` | Switch tabs |
| `browser_get_info` | Page URL and title |
| `browser_get_browser_info` | Browser information |
| `browser_check_stealth` | Check stealth mode |
| `browser_close` | Close the browser |
### Profiles and Cookies
| Tool | Description |
|------------|----------|
| `browser_auto_connect` | Auto-detect profile with cookies and launch browser |
| `browser_list_profiles` | List available browser profiles |
| `browser_detect_active_profile` | Determine which profile is being used |
| `browser_get_cookies` | Get cookies for the current session |
| `browser_set_cookie` | Set a cookie |
| `browser_delete_cookie` | Delete a cookie |
| `browser_connect` | Connect to an already launched browser |
| `browser_start_with_debug` | Launch browser with debug port |
## Working with Profiles
### Auto-detect Profile (easiest way!)
```javascript
// Automatically find a profile with cookies and launch browser
browser_auto_connect({
browser: "chrome",
url: "https://github.com" // optional
})
// Or through browser_navigate with profile="auto"
browser_navigate({
url: "https://github.com",
profile: "auto" // auto-detect profile
})
```
The server automatically:
1. Searches for Chrome/Firefox/Edge/Brave profiles in standard paths
2. Reads `Local State` to find the last used profile
3. Checks for Cookies files
4. Launches browser with the found profile
### Connecting to an already launched browser (easiest way!)
If Chrome is already open with authorization, connect to it:
```bash
# 1. Launch Chrome with debug port (once)
google-chrome --remote-debugging-port=9222
# 2. Connect through MCP
browser_connect({ port: 9222 })
```
Or launch browser through MCP:
```javascript
browser_start_with_debug({
browser: "chrome",
port: 9222,
profile: "default" // use existing profile
})
// Then connect
browser_connect({ port: 9222 })
```
**Important**: When `browser_close()` the server will disconnect from the browser, but **not** close it - you can continue working in the browser manually.
### Auto-detection of active profile
```javascript
// Determine which profile is being used
browser_detect_active_profile({ browser: "chrome" })
// Returns: profile name, path, cookies, browser launched
```
### Using a real profile (with cookies and authorization)
```javascript
// Use the main Chrome profile (all cookies and sessions)
browser_navigate({
url: "https://github.com",
profile: "default"
})
// Use a specific profile
browser_navigate({
url: "https://github.com",
profile: "default",
profileName: "Profile 1"
})
// Specify a custom profile path
browser_navigate({
url: "https://github.com",
profile: "custom",
profilePath: "/home/user/.config/google-chrome"
})
// Without profile (clean session)
browser_navigate({
url: "https://github.com",
profile: "none"
})
```
### Viewing available profiles
```javascript
// Find all Chrome profiles
browser_list_profiles({ browser: "chrome" })
// Determine the active profile
browser_detect_active_profile({ browser: "chrome" })
```
### Working with cookies
```javascript
// View all cookies
browser_get_cookies()
// Cookies for a specific domain
browser_get_cookies({ url: "https://github.com" })
// Set a cookie
browser_set_cookie({
name: "session",
value: "abc123",
domain: ".github.com"
})
// Delete a cookie
browser_delete_cookie({
name: "session",
domain: ".github.com"
})
```
### Environment Variables
```bash
# Specify profile path
export BROWSER_PROFILE_PATH="~/.config/google-chrome"
# Specify browser path
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"
```
## Example Usage (prompt for LLM)
```
Open GitHub with my profile (profile="default"), find my repository, and create a new issue.
```
```
Log in to the site with authorization. Use profile="default" to save the session.
After logging in, get cookies and save them.
```
## Automation (example)
```bash
# Example sequence of actions through MCP:
1. browser_navigate(url="https://github.com", profile="default")
2. browser_click(selector="a[href='/login']")
3. browser_wait(selector="input[name='login']", timeout=5000)
4. browser_type(selector="input[name='login']", text="myuser")
5. browser_type(selector="input[name='password']", text="mypass")
6. browser_click(selector="input[type='submit']")
7. browser_wait(selector=".dashboard", timeout=10000)
8. browser_screenshot()
```
## Requirements
- Node.js 18+
- One of the browsers: Chrome, Chromium, Edge, Brave, Opera, or Firefox
- ~200MB of space for the browser
### Auto-detection of browser
The server automatically searches for browsers in standard paths:
- `/usr/bin/google-chrome`
- `/snap/bin/chromium`
- `/usr/bin/microsoft-edge`
- `/usr/bin/brave-browser`
- `/usr/bin/firefox`
### Auto-detection of profiles
The server searches for profiles in standard paths:
- Chrome: `~/.config/google-chrome`, `~/.config/chromium`
- Firefox: `~/.mozilla/firefox`
- Edge: `~/.config/microsoft-edge`
- Brave: `~/.config/BraveSoftware/Brave-Browser`
Specify `BROWSER_PROFILE_PATH` if profiles are in a non-standard location.
### Important
When using a real profile **do not launch the browser twice** - this can damage data. If the browser is already open, close it manually before using the MCP server.
## License
MIT
