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.

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.

Related MCP server: pilot-browser-mcp

Установка

Нужен macOS. Установщик сам поставит uv и, если есть Homebrew, Node.js 20+.

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 («яндекс», chrome, «сафари»). По умолчанию используется системный браузер.

Как устроено

• Сервер (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

{"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 и напишет об этом в лог.

Разработка

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.