Chrome Browser MCP

Локальный мост, который позволяет частному приложению ChatGPT в режиме разработчика просматривать вкладки, уже открытые в вашем настольном Google Chrome, и управлять ими.

Текущая версия патча: 0.1.2. Каждый патч должен увеличивать эту версию; CI отклоняет патчи, которые этого не делают.

Мост предоставляет 17 инструментов MCP:

• чтение: browser_status, list_tabs, get_active_tab, read_tab, read_tabs, search_tabs

• действия: click, type, fill_form, press_key, scroll, select_option, navigate, new_tab, close_tab

• дочерние агенты ChatGPT: spawn_chatgpt_agent, read_chatgpt_agent

spawn_chatgpt_agent по умолчанию открывает новую вкладку chatgpt.com в фоновом режиме, отправляет ровно тот запрос, который предоставил пользователь, и возвращает её идентификатор вкладки. read_chatgpt_agent читает эту дочернюю вкладку через тот же ограниченный семантический экстрактор, который используется для обычных вкладок; вызовите его снова позже, если дочерняя вкладка всё ещё генерирует ответ.

Цели действий принимают либо CSS-селектор, либо точный видимый текст / aria-label / placeholder / имя / текст связанной метки. Неоднозначные цели приводят к ошибке, а не к угадыванию.

Мост не предоставляет доступ к cookies, локальному хранилищу, хранилищу сеанса, сохранённым паролям, скрытым значениям полей ввода, произвольному выполнению JavaScript, внутренним страницам Chrome или вкладкам режима инкогнито. Он не использует Chrome debugger API.

Проверенный путь

Сквозной тест запускает реальный процесс Chromium с распакованным расширением Manifest V3, запускает реальный хост native-messaging, подключает MCP-клиент через Streamable HTTP, открывает живые страницы, перечисляет и читает их, а также проверяет, что значение поля ввода пароля не возвращается. Покрытие модульными и интеграционными тестами проверяет действия на страницах, маршрутизацию MCP, регистрацию/композицию инструментов дочернего агента ChatGPT, синхронизацию сгенерированной версии расширения, а также то, что файлы времени выполнения, используемые Chrome/native messaging, отслеживаются Git.

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

Запустите все проверки:

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

Архитектура

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

Chrome запускает нативный хост при подключении расширения. Нативный хост запускает конечную точку MCP на loopback. Поэтому Chrome должен быть открыт, а расширение — включено всякий раз, когда ChatGPT использует приложение.

Требования

• macOS

• Google Chrome 120+

• Node.js 20+

• Учётная запись ChatGPT с доступным Developer Mode

• Идентификатор туннеля OpenAI Platform и runtime API-ключ с правами Tunnels Read + Use

• tunnel-client

1. Установите нативный хост и один раз загрузите расширение

npm run install:mac

Это устанавливает манифест нативного хоста в:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

Затем:

1. Откройте chrome://extensions.

2. Включите Developer mode.

3. Нажмите Load unpacked.

4. Выберите каталог dist/extension этого репозитория.

5. Убедитесь, что идентификатор расширения точно такой:

jlpddlfiallighiohmhhkemgbhofpnha

Не продолжайте, если идентификатор отличается. Нативный хост принимает только этот конкретный origin расширения.

2. Обновление будущих патчей

Вы выбираете каталог расширения только один раз. Собранное расширение и MCP-мост в dist/ закоммичены в Git, и CI отклоняет изменения исходного кода, у которых закоммиченная runtime-сборка устарела.

Для каждого последующего патча обычный процесс обновления выглядит ровно так:

git pull

Затем откройте chrome://extensions и нажмите Update. Не выбирайте путь к расширению повторно и не запускайте отдельную команду сборки только для применения опубликованного патча.

git pull обновляет и dist/extension (то, что загружает Chrome), и dist/bridge (то, что выполняет нативный хост). Нажатие Update перезагружает распакованное расширение и соединение native-messaging, чтобы использовалась только что полученная runtime-версия.

Отображаемая версия расширения должна меняться при каждом патче. Для этого патча она должна показывать 0.1.2. Если она по-прежнему показывает более старую версию, полученный runtime не был применён.

3. Проверьте локальную цепочку браузера

Держите Chrome открытым, затем выполните:

npm run verify:local

При успешной проверке выводятся:

• идентификатор расширения;

• версия расширения;

• версия MCP-сервера;

• 17 заявленных инструментов MCP.

Проверка завершается ошибкой, если версии расширения и MCP различаются или если мост настолько старый, что не сообщает свою версию MCP. Это позволяет сразу отличить устаревший мост с 15 инструментами от устаревшего расширения Chrome.

4. Настройте Secure MCP Tunnel

Создайте туннель и runtime API-ключ в OpenAI Platform. Затем:

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

Профиль перенаправляет туннель на:

http://127.0.0.1:2091/mcp

Держите tunnel-client run активным всегда, когда ChatGPT нужны инструменты браузера.

5. Добавьте его в ChatGPT

1. В ChatGPT включите Settings -> Security and login -> Developer mode.

2. Откройте Settings -> Plugins.

3. Нажмите +, чтобы создать приложение в режиме разработчика.

4. Выберите Tunnel в качестве типа подключения.

5. Выберите или вставьте идентификатор туннеля.

6. Используйте метаданные из app-metadata.json.

7. Убедитесь, что ChatGPT обнаруживает все 17 инструментов.

8. В новом чате нажмите + -> More, выберите Chrome Browser и спросите: List my open Chrome tabs.

Точную проверку и устранение неполадок см. в docs/CHATGPT_SETUP.md.

Модель безопасности

Текст веб-страниц — это данные, а не источник авторитета. Каждый результат чтения контента содержит явную пометку о недоверенном содержимом, а инструкции инструментов предписывают модели никогда не превращать инструкции, найденные на страницах, в действия.

Расширение намеренно запрашивает доступ ко всем HTTP- и HTTPS-страницам, чтобы читать обычные открытые вкладки и взаимодействовать с ними. Граница защиты такова:

• расширение загружается локально вами;

• Chrome запускает только именно тот нативный хост, который внесён в список разрешённых;

• нативный хост отклоняет любой origin, кроме стабильного идентификатора расширения;

• конечная точка MCP привязывается только к 127.0.0.1;

• туннель предназначен только для исходящих соединений;

• действия ограничены обычными вкладками HTTP(S) и не открывают доступ к произвольному JavaScript, отладчику, cookies или хранилищу браузера;

• неоднозначные человекочитаемые цели отклоняются, а не угадываются.

Прочтите THREAT_MODEL.md и SECURITY_REVIEW.md перед использованием без присмотра.

Известные ограничения

• В один момент времени расширение должно загружать только один профиль Chrome; два профиля могут конкурировать за порт 2091.

• Внутренние страницы Chrome, страницы Chrome Web Store, страницы file:// и вкладки режима инкогнито нельзя читать или контролировать.

• Кросс-доменные iframe не обходятся.

• Приложения, использующие только Canvas, и встроенный PDF-просмотрщик Chrome могут возвращать мало семантического текста.

• Экстрактор возвращает видимый текст, заголовки, ссылки и описание основного документа, а не исходный HTML. Учётные данные и фрагменты в URL удаляются, а конфиденциальные параметры запроса скрываются.

• press_key использует DOM-события клавиатуры; для Enter и Escape задано явное поведение для стандартных случаев, но некоторым сайтам требуется доверенный ввод с клавиатуры через ОС/CDP.

• Отправка запроса дочернего агента ChatGPT зависит от текущего веб-композера ChatGPT (#prompt-textarea) и разметки кнопки отправки; будущее изменение интерфейса ChatGPT может потребовать обновления этих селекторов.

• read_chatgpt_agent возвращает видимый семантический текст страницы дочерней вкладки, а не привилегированный ответ API ChatGPT.

• Загрузка файлов намеренно не реализована, поскольку её универсальная реализация потребовала бы более мощного интерфейса файловой системы/отладчика.

Разработка

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit