# OctoBrowser MCP Server

[English](#english) | [Русский](#russian)

---

## English

### Description

MCP (Model Context Protocol) server for OctoBrowser automation. This server enables Claude Desktop to interact with OctoBrowser, providing browser automation capabilities through a standardized protocol interface.

### Features

- **Profile Management**: Create, read, update, and delete browser profiles
- **Tag Management**: Organize profiles with tags
- **Proxy Management**: Configure and manage proxy settings
- **Cookie Import**: Import cookies into profiles
- **Local Control**: Start and stop profiles on local machine
- **Active Monitoring**: Check currently running profiles

### Installation

#### Manual Installation

1. Clone the repository:
```bash
git clone https://github.com/momentum100/octobrowser-mcp-server.git
cd octobrowser-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Configure Claude Desktop by adding the following to your Claude Desktop configuration file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
    "mcpServers": {
        "mcp-octobrowser": {
            "command": "node",
            "args": [
                "C:\\mcp-servers\\mcp-octo-browser\\dist\\index.js"
            ],
            "env": {
                "OCTOBROWSER_API_TOKEN": "YOUR_API_KEY_HERE"
            }
        }
    }
}
```

5. Replace `YOUR_API_KEY_HERE` with your actual OctoBrowser API token.

6. Adjust the path in `args` to match your installation directory.

7. Restart Claude Desktop to apply the configuration.

### Requirements

- Node.js 16 or higher
- npm or yarn
- OctoBrowser API token
- Claude Desktop application

### Configuration

The server requires the following environment variable:
- `OCTOBROWSER_API_TOKEN`: Your OctoBrowser API authentication token

Optional environment variables:
- `OCTOBROWSER_API_URL`: API base URL (default: https://app.octobrowser.net)
- `OCTOBROWSER_LOCAL_URL`: Local client URL (default: http://localhost:58888)

### Available Tools

#### Profile Management
- `octobrowser_get_profiles` - Get list of profiles with optional filtering
- `octobrowser_get_profile` - Get detailed profile information
- `octobrowser_create_profile` - Create a new browser profile
- `octobrowser_update_profile` - Update existing profile
- `octobrowser_delete_profiles` - Delete one or more profiles
- `octobrowser_import_cookies` - Import cookies into a profile

#### Tag Management
- `octobrowser_get_tags` - Get all available tags
- `octobrowser_create_tag` - Create a new tag
- `octobrowser_update_tag` - Update tag name
- `octobrowser_delete_tag` - Delete a tag

#### Proxy Management
- `octobrowser_get_proxies` - Get all configured proxies
- `octobrowser_create_proxy` - Add a new proxy configuration
- `octobrowser_update_proxy` - Update proxy settings
- `octobrowser_delete_proxy` - Remove a proxy

#### Local Profile Control
- `octobrowser_get_active_profiles` - List currently running profiles
- `octobrowser_start_profile` - Start a profile (GUI or headless)
- `octobrowser_stop_profile` - Stop a running profile

### API Token

To get your OctoBrowser API token:
1. Log in to your OctoBrowser account
2. Navigate to API settings
3. Generate or copy your API token

---

## Russian

### Описание

MCP (Model Context Protocol) сервер для автоматизации OctoBrowser. Этот сервер позволяет Claude Desktop взаимодействовать с OctoBrowser, предоставляя возможности автоматизации браузера через стандартизированный интерфейс протокола.

### Возможности

- **Управление профилями**: Создание, чтение, обновление и удаление профилей браузера
- **Управление тегами**: Организация профилей с помощью тегов
- **Управление прокси**: Настройка и управление параметрами прокси
- **Импорт куки**: Импорт куки в профили
- **Локальное управление**: Запуск и остановка профилей на локальной машине
- **Активный мониторинг**: Проверка запущенных профилей

### Установка

#### Ручная установка

1. Клонируйте репозиторий:
```bash
git clone https://github.com/momentum100/octobrowser-mcp-server.git
cd octobrowser-mcp-server
```

2. Установите зависимости:
```bash
npm install
```

3. Соберите проект:
```bash
npm run build
```

4. Настройте Claude Desktop, добавив следующую конфигурацию в файл настроек Claude Desktop:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
    "mcpServers": {
        "mcp-octobrowser": {
            "command": "node",
            "args": [
                "C:\\mcp-servers\\mcp-octo-browser\\dist\\index.js"
            ],
            "env": {
                "OCTOBROWSER_API_TOKEN": "ВАШ_API_КЛЮЧ"
            }
        }
    }
}
```

5. Замените `ВАШ_API_КЛЮЧ` на ваш актуальный токен API OctoBrowser.

6. Измените путь в `args` в соответствии с вашей директорией установки.

7. Перезапустите Claude Desktop для применения конфигурации.

### Требования

- Node.js версии 16 или выше
- npm или yarn
- Токен API OctoBrowser
- Приложение Claude Desktop

### Конфигурация

Сервер требует следующую переменную окружения:
- `OCTOBROWSER_API_TOKEN`: Ваш токен аутентификации API OctoBrowser

Дополнительные переменные окружения:
- `OCTOBROWSER_API_URL`: Базовый URL API (по умолчанию: https://app.octobrowser.net)
- `OCTOBROWSER_LOCAL_URL`: URL локального клиента (по умолчанию: http://localhost:58888)

### Доступные инструменты

#### Управление профилями
- `octobrowser_get_profiles` - Получить список профилей с опциональной фильтрацией
- `octobrowser_get_profile` - Получить детальную информацию о профиле
- `octobrowser_create_profile` - Создать новый профиль браузера
- `octobrowser_update_profile` - Обновить существующий профиль
- `octobrowser_delete_profiles` - Удалить один или несколько профилей
- `octobrowser_import_cookies` - Импортировать куки в профиль

#### Управление тегами
- `octobrowser_get_tags` - Получить все доступные теги
- `octobrowser_create_tag` - Создать новый тег
- `octobrowser_update_tag` - Обновить название тега
- `octobrowser_delete_tag` - Удалить тег

#### Управление прокси
- `octobrowser_get_proxies` - Получить все настроенные прокси
- `octobrowser_create_proxy` - Добавить новую конфигурацию прокси
- `octobrowser_update_proxy` - Обновить настройки прокси
- `octobrowser_delete_proxy` - Удалить прокси

#### Локальное управление профилями
- `octobrowser_get_active_profiles` - Список запущенных профилей
- `octobrowser_start_profile` - Запустить профиль (GUI или headless)
- `octobrowser_stop_profile` - Остановить запущенный профиль

### API токен

Чтобы получить токен API OctoBrowser:
1. Войдите в свою учетную запись OctoBrowser
2. Перейдите в настройки API
3. Сгенерируйте или скопируйте ваш API токен

---

## Development / Разработка

### Project Structure / Структура проекта

```
mcp-octo-browser/
├── src/
│   └── index.ts        # Main server implementation
├── dist/               # Compiled JavaScript (generated)
├── package.json        # Node.js dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md          # Documentation
```

### Building / Сборка

```bash
npm run build
```

### Development Mode / Режим разработки

```bash
npm run dev
```

## License

MIT

## Support

For issues and questions, please visit: https://github.com/momentum100/octobrowser-mcp-server/issues