Browser MCP

Предоставьте ваш браузер Chrome/Edge как инструменты MCP для любого ИИ-агента. Расширение Chrome (Manifest V3) само выступает в роли MCP-сервера: оно подключается к code-mcp-gateway и отвечает на MCP-запросы на месте — локальный сервер не требуется. Оно говорит на том же протоколе JSON-RPC, что и code-mcp, поэтому легко встраивается в существующие настройки агентов.

Как это работает

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

Всплывающее окно принимает Device ID и Token; расширение подключается напрямую к шлюзу (регистрация, keepalive каждые 25 с, watchdog 75 с, переподключение с джиттером и экспоненциальной задержкой) и обслуживает initialize / tools/list / tools/call на месте. Любой агент, который может достичь шлюза, может управлять браузером.

Опциональный локальный сервер (browser-mcp.ts) добавляет файловое хранилище (file_read, большие загрузки/скачивания) и простую локальную MCP HTTP-конечную точку. См. Локальный сервер.

Быстрый старт

Chrome или Edge >= 111. Bun >= 1.1 нужен только для локального сервера или инструментов разработки — расширение работает автономно.

1. Загрузите расширение. Откройте chrome://extensions, включите Режим разработчика, нажмите Загрузить распакованное и выберите packages/browser-extension. (Или запустите bun browser-mcp.ts и скачайте zip с http://127.0.0.1:7777/extension.)

2. Подключитесь. Нажмите на значок на панели инструментов (метка MCP становится зелёной при подключении). Введите Device ID и Token шлюза, нажмите Подключиться. Всплывающее окно покажет Подключено (шлюз).

3. Используйте. Направьте любого MCP-клиента на ваше устройство шлюза. Расширение отвечает на tools/list 47 инструментами.

Токен должен совпадать с токеном, настроенным для этого устройства на шлюзе. Шлюз передаёт его с каждым запросом, а расширение проверяет его. Если оставить его пустым, любой, кто достигнет шлюза, сможет управлять браузером.

Локальный сервер

Нужен только для файлового хранилища (file_read, загрузок/скачиваний > 512 КБ) или локальной MCP HTTP-конечной точки:

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

При запущенном сервере всплывающее окно также передаёт ID + Token на собственную ссылку шлюза сервера; без него расширение всё равно работает напрямую. Локальные клиенты используют http://127.0.0.1:7777/mcp — см. mcp-client.example.json (добавьте "headers": { "Authorization": "Bearer <token>" }, если запускаете с --token). Проверка: curl -s http://127.0.0.1:7777/health.

Удалённый доступ через code-mcp-gateway

• Прямой (по умолчанию). Введите ID + Token во всплывающем окне; расширение само обслуживает MCP. Локальный сервер не нужен.

• Серверная привязка. С локальным сервером всплывающее окно подключается к wss://code-mcp.tuanm.dev/ws/<id>, и сервер отвечает на MCP через HTTP.

• CLI (пользовательский шлюз):

bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

Тот же протокол, что и в прямом режиме. Используйте тот же --token на устройстве шлюза; никогда не запускайте режим шлюза без него. Установите BMCP_GATEWAY_DOMAIN, чтобы переопределить хост шлюза по умолчанию во всплывающем окне.

Инструменты (47)

Обнаружение элементов с помощью системы @ref: snapshot возвращает интерактивное дерево элементов с маркерами [ref=eN]; каждый инструмент взаимодействия принимает ref или CSS-селектор (refs кэшируются и разрешаются автоматически; устаревшие refs вызывают ошибку «run snapshot again»).

• Обнаружение — snapshot, find (role/name/text/label/placeholder/title/testid/selector), get, is

• Взаимодействие — click, dblclick, type, fill, check, uncheck, select, hover, focus, press, drag, scroll, upload

• Навигация — navigate, reload, back, forward, close, tabs, window

• Чтение страницы — extract, execute, screenshot (блок изображения), pdf, wait, highlight

• Состояние и отладка — store, cookies, storage, console, errors, network, status, file_read

• Эмуляция и управление — emulate, set (viewport/device/geo/offline/headers/media), perms, auth, dialog, frames, touch, download

Захват console/errors/network начинается при первом вызове (лениво), поэтому после включения перезагрузите страницу или выполните навигацию, чтобы захватить трафик. Back/forward используют историю навигации CDP. Выполните curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' для полных схем.

Флаги

Безопасность

• Ограничение по Origin. /browser/ws принимает только origin'ы chrome-extension://; /mcp и /files/* отклоняют браузерные origin'ы, кроме localhost — вредоносный сайт не сможет управлять вашим браузером через localhost (CSRF). Нативные MCP-клиенты (без заголовка Origin) не затрагиваются.

• --token ограничивает доступ к /mcp и /files/* (?token= или Bearer); --extension-token добавляет секрет, который расширение должно предъявлять на bridge.

• File ID — это 12-значный случайный hex, проверяемый по строгому шаблону; имена загружаемых файлов санируются. Ограничения размера: загрузки 500 МиБ, скриншоты 8 МиБ инлайн.

• chrome.debugger показывает жёлтую инфопанель, пока подключён (сигнал согласия); perms/cookies используют API, не связанные с отладчиком, где это возможно.

• По умолчанию привязывается к 127.0.0.1; привязка к 0.0.0.0 без --token выводит предупреждение.

Тайм-ауты

Команды bridge: 30 с по умолчанию, 60 с для navigate/execute/wait_for, 120 с для download/file_upload — максимум 120 с локально и 55 с в режиме шлюза (шлюз прерывает пересылку через 60 с). Инструменты принимают bridge_timeout для переопределения.

Разработка

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server