# browser-mcp

MCP server that lets any AI agent (Claude Code, Claude Desktop, Cursor…) work in **your real
browsers with your logins** — Yandex Browser, Chrome, Edge, Brave, Safari — in the background,
without stealing focus, in the tab group that fits the task. macOS.

```bash
curl -fsSL https://raw.githubusercontent.com/AlexB00M/browser-mcp/main/install.sh | bash
```

---

## Что это

MCP-сервер `browser` даёт нейросети ваш настоящий браузер, тот, где вы уже вошли на все сайты:

- **работает в фоне.** Вкладки агента не становятся активными, а курсор и клавиатура остаются
  вашими. Вы спокойно пользуетесь браузером, пока агент делает своё;
- **сам решает, показывать или нет.** Если вы за компьютером и просили показать — откроет у вас
  на экране, иначе работает в фоне;
- **раскладывает по группам вкладок.** Выбирает группу по смыслу задачи («учёба», «работа»…);
  если подходящей нет — спросит вас и предложит создать новую. До ответа работает в группе по
  умолчанию, а если она не задана, то в главной (основное пространство Яндекса, в Chrome —
  вкладки без группы). В ту группу, которую вы сейчас смотрите, не лезет;
- **убирает за собой.** По окончании задачи закрывает вспомогательные вкладки и оставляет то,
  что вам нужно;
- **быстро.** Несколько действий за один ход (`browser_steps`). Удачную задачу можно сохранить
  как сценарий и повторять без нейросети за секунды (`browser_scenario_run`);
- **разные агенты не мешают друг другу.** Каждый работает в своём браузере, группе и вкладках.

Страницы агент читает компактным текстовым «снимком доступности» (кнопки, поля, ссылки с
метками), а не скриншотами и не HTML. Большую страницу сервер сам урезает по глубине примерно
до 16 КБ (около 4 тысяч токенов) и подсказывает, как получить нужный блок; целиком — только
по `full=true`.

## Установка

Нужен macOS. Установщик сам поставит [uv](https://docs.astral.sh/uv/) и, если есть Homebrew,
Node.js 20+.

```bash
curl -fsSL https://raw.githubusercontent.com/AlexB00M/browser-mcp/main/install.sh | bash
```

Что он делает:
1. ставит сервер (`uv tool install`) и Playwright MCP;
2. регистрирует сервер в Claude Code и Claude Desktop, а для других клиентов печатает JSON;
3. копирует расширение `browser` в `~/.browser/extension` и открывает страницу расширений во
   всех установленных Chromium-браузерах.

**Один шаг руками** (браузеры не дают поставить расширение без вас): на открывшейся странице
расширений включите «Режим разработчика» → «Загрузить распакованное расширение» → выберите
`~/.browser/extension`. Скрытую папку в окне выбора открывает **Cmd+Shift+G** с этим путём.

Перезапустите Claude Desktop или Claude Code, и всё готово. Проверка — попросите агента:
«какие браузеры и группы вкладок у меня есть?».

Другие клиенты MCP (Cursor, Windsurf…): команда сервера — `~/.local/bin/browser`.

## Что умеет

| Инструменты | Зачем |
|---|---|
| `browser_open`, `browser_search`, `browser_list_tabs`, `browser_focus_tab`, `browser_close_tab`, `browser_new_tab`, `browser_reload`, `browser_back` | вкладки: открыть сайт или поиск (в фоне или с показом), найти, показать, закрыть |
| `browser_groups`, `browser_group_create`, `browser_group_delete`, `browser_set_default_group` | группы вкладок |
| `browser_snapshot`, `browser_click`, `browser_type`, `browser_fill_form`, `browser_navigate`, `browser_find`… | работа со страницей: те же имена и параметры, что у [Playwright MCP](https://github.com/microsoft/playwright-mcp), плюс `browser`, `group`, `show` |
| `browser_steps` | цепочка действий за один вызов, со снимком страницы в конце |
| `browser_scenario_save` / `_run` / `_delete`, `browser_scenarios` | сценарии: сохранить удачную задачу и повторять без нейросети |
| `browser_use`, `browser_list`, `browser_session`, `browser_finish` | выбор браузера, группы и режима показа для сессии; что открыто; уборка |

У каждого инструмента есть необязательный параметр `browser` («яндекс», `chrome`, «сафари»).
По умолчанию используется системный браузер.

| Браузер | Вкладки | Работа со страницей | Группы |
|---|---|---|---|
| Chrome, Edge, Brave, Chromium | ✅ | ✅ | ✅ создать, удалить, положить вкладку |
| Яндекс Браузер | ✅ | ✅ | ✅ список, положить и перенести вкладку; создаёт и удаляет группы только человек (у Яндекса нет для этого API) |
| Safari | ✅ | — | — |
| Firefox, Arc, Opera | только открыть ссылку | Arc, Opera — ✅ | — |

## Как устроено

- **Сервер (Python).** Вкладки работают через расширение, а если его нет — через AppleScript.
  Страницы — через Playwright MCP (закреплённая версия, по одному процессу на браузер,
  запускается при первом обращении и завершается после 5 минут простоя).
- **Расширение `browser`.** Отвечает за группы, фоновые вкладки и подключение Playwright без
  перехвата фокуса. В скрытой вкладке Chromium не доставляет события мыши и клавиатуры, поэтому
  расширение воспроизводит их внутри страницы. Сервер связывается с расширением через
  native messaging (`browser-native-host`, сокет `~/.browser/run/<браузер>.sock`).
- **Правила для нейросети** (показ или фон, выбор группы, что закрывать, как экономить ходы)
  записаны в инструкциях MCP-сервера. Их получает любой клиент.

Память: сервер около 70 МБ, Playwright около 135 МБ, пока агент работает со страницами (потом
выгружается), native host около 17 МБ. Файлы Playwright в `~/.browser/output` ограничены 20 МБ.
Сценарии — маленькие JSON-файлы в `~/.browser/scenarios` (права 600). Ввод паролей и кодов в
сценарии не сохраняется.

Ограничения фона: события в скрытой вкладке синтетические, и редкие сайты их не принимают.
Тогда агент работает с показом.

## Настройки — `~/.browser/config.json`

```json
{"default_group": "Агент", "default": null}
```

`default_group` — группа для задач без подходящей группы (если не задана — главная группа).
`default` — браузер, если не нужен системный. `BROWSER_SETTLE_MS` — пауза после действия
(по умолчанию 250 мс).

## Голосовые команды (необязательно)

Если рядом установлен пакет `jarvis-mcp` голосового ассистента Jarvis (`uv tool install
browser-mcp --with <путь к jarvis-mcp>`), сервер публикует для него быстрые голосовые команды: «открой ютуб», «найди в интернете …», «закрой вкладку», «какие группы вкладок»,
«запусти сценарий …». Без него это обычный MCP-сервер.

### Обновление Playwright

Версия `@playwright/mcp` закреплена (`PLAYWRIGHT_MCP_VERSION` в `browser/config.py`): сам по
себе сервер не обновится и не сломается. Раз в неделю GitHub Action `playwright-update`
проверяет новую версию на тестах (инструменты и параметры, патч фоновой работы) и открывает
PR, если тесты зелёные, или issue, если красные. Перед слиянием PR нужна живая проверка:
`uv tool install --force .`, затем попросить агента открыть страницу в фоне, кликнуть и ввести
текст. Установленные копии сами поставят новую версию Playwright при первом обращении к
странице. Если Playwright сменит протокол расширения, сервер переключится на официальное
Playwright Extension и напишет об этом в лог.

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

```bash
uv run pytest                       # тесты, включая сверку с настоящим Playwright MCP, если он стоит
uv run ruff check browser tests
uv tool install --force . && browser-setup --no-open
```

Код ретрансляции в `browser/extension/background.js` адаптирован из Playwright Extension
(Microsoft, Apache-2.0, `browser/extension/LICENSE-playwright`). Остальное — MIT.