browser-search-mcp

v0.1.4

Published

17 days ago

Zero-config browser web search MCP server. Auto-installs Python runtime and Chromium, then serves a local Streamable HTTP MCP endpoint.

0High
0Medium
0Low

aiplatforms

mcp model-context-protocol search web-search playwright browser llm ai research

English

browser-search-mcp is a Model Context Protocol server that gives an LLM client browser-based web search tools.

It starts a local FastAPI search gateway and a Streamable HTTP MCP server. On the first run it creates an isolated Python virtual environment, installs Python dependencies, downloads Chromium through Playwright, and then exposes:

MCP endpoint: http://127.0.0.1:8892/mcp
Search API: http://127.0.0.1:8891

The search layer uses a real Chromium browser and can query Google, Bing, Yahoo, and DuckDuckGo, with fallback and result de-duplication.

Built by AI Platforms — on-premises LLM and computer-vision systems for enterprises that need their AI to stay inside their own server room.

Why browser search

Many LLM clients either have no web access, rely on a single hosted search API, or need you to wire up several keys before anything useful happens. browser-search-mcp is designed for local/private AI setups where:

You want one npx command, not a manual Python deployment.
You want real browser search pages instead of a vendor-specific search API.
You want several engines and fallbacks when one engine blocks, returns too little, or changes markup.
You want an MCP tool that can first scan snippets and then extract selected pages when deeper reading is needed.

The Node package is only a launcher. The actual runtime lives in ~/.browser-search-mcp by default, so npm cache and package directories stay small.

Quick start

npx browser-search-mcp

First run may take a few minutes: Python packages and Chromium are downloaded. After setup, point your MCP client at:

http://127.0.0.1:8892/mcp

For stdio-only MCP clients, run:

npx browser-search-mcp --stdio

Global install is also supported:

npm i -g browser-search-mcp
browser-search-mcp

Requirements

Node.js 18+ for npx / npm.
Python 3.10+ available on PATH.
Internet access on first run to install Python dependencies and Chromium.
About 500 MB of disk space for the isolated runtime.
Windows, Linux, or macOS.

Configuration

Ports and runtime location can be changed with environment variables:

| Variable | Default | Description | |----------|---------|-------------| | BROWSER_SEARCH_MCP_HOME | ~/.browser-search-mcp | Runtime directory for venv, install sentinel, and logs. | | API_PORT | 8891 | Local FastAPI search gateway port. | | MCP_HOST | 127.0.0.1 | MCP HTTP bind host. | | MCP_PORT | 8892 | MCP HTTP port. | | SEARCH_API_TIMEOUT | 300 | MCP-to-search API timeout, seconds. | | LOG_DIR | ~/.browser-search-mcp/logs | Search API log directory. |

Windows PowerShell:

$env:API_PORT = "8891"
$env:MCP_PORT = "8892"
npx browser-search-mcp

macOS / Linux:

API_PORT=8891 MCP_PORT=8892 npx browser-search-mcp

Tools

| Tool | What it does | |------|--------------| | web_search | Run one search query and return titles, URLs, and snippets. Can optionally extract content from top results. | | deep_research | Run a research round over 1-10 model-selected queries and return grouped search results. | | extract_webpage | Extract readable text from one known URL. | | extract_webpages | Extract readable text from up to 20 selected URLs. |

All search tools require the model to choose an engine:

auto
google
bing
yahoo
duckduckgo
yandex
mailru

With engine=auto, the server tries engines in order and keeps collecting unique links until the requested result count is reached.

HTTP API

The package also exposes a plain HTTP API on http://127.0.0.1:8891.

Search:

curl -X POST http://127.0.0.1:8891/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"Python asyncio tutorial","num_results":5,"engine":"auto","extract_content":false}'

Extract a page:

curl -X POST http://127.0.0.1:8891/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","max_length":4000}'

Other endpoints:

| Endpoint | Description | |----------|-------------| | GET /api/health | Health check. | | GET /api/search/simple?q=...&n=3&engine=duckduckgo | Simple GET search. | | GET /api/tools | OpenAI-style tool definitions. | | GET /api/tools/openrouter | OpenRouter-compatible tool definitions. | | GET /docs | Swagger UI. |

Integrations

This package runs a Streamable HTTP MCP server. Use this URL in any MCP client that supports remote/HTTP MCP servers:

http://127.0.0.1:8892/mcp

For stdio-only clients such as local OpenCode MCP entries, use:

{
  "mcp": {
    "browser-search-mcp": {
      "type": "local",
      "command": ["npx", "-y", "browser-search-mcp", "--stdio"],
      "enabled": true,
      "timeout": 1800000
    }
  }
}

Typical workflow:

Start the server:
```
npx browser-search-mcp
```
Add http://127.0.0.1:8892/mcp to your MCP client's server list.
Enable the server in the chat/tool settings.
Ask the model to search, verify, research, or extract a page.

For llama.cpp Web UI, enable MCP proxy support in llama-server, add the MCP URL above in MCP Servers, and enable the server in the chat tools menu.

Example chat workflow

Use the browser-search-mcp MCP. Search for the latest Playwright Python release notes with engine=auto, return the strongest sources, then extract the official release page and summarize the breaking changes.

Typical tool sequence:

web_search with a focused query and engine=auto.
web_search again with another engine if results are sparse.
extract_webpage for the official documentation or release page.
Final answer with source-grounded summary.

How it works

MCP client ── Streamable HTTP ──► MCP server (:8892/mcp)
                                      │
                                      ▼
                              Search API (:8891)
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
          Chromium search pages              Page fetch + extraction
 Google / Bing / Yahoo / DDG / Yandex / Mail.ru  Playwright + trafilatura

The API starts Chromium in headless mode through Playwright. Search result DOMs are parsed into title, URL, and snippet records. Page extraction uses Chromium for loading and trafilatura / BeautifulSoup for readable text.

Security and privacy

Search queries and extracted page content pass through your local MCP client and local runtime.
The package downloads Python dependencies and Chromium on first run.
Search engines and websites you query can see requests from your machine.
There are no API keys or hosted search credentials in the package.
Runtime files are stored in ~/.browser-search-mcp unless overridden.
This is a local browser automation tool; it is not an anonymizer.

Development

The npm package contains:

bin/
  cli.js              Node launcher: venv bootstrap + API/MCP process startup
api/
  server.py           FastAPI browser search gateway
  mcp_server.py       Streamable HTTP MCP bridge
  requirements.txt    Python runtime dependencies

Local syntax checks:

node --check bin/cli.js
python -m py_compile api/server.py api/mcp_server.py
npm pack --dry-run

Русский

browser-search-mcp — это MCP-сервер, который даёт LLM-клиенту инструменты веб-поиска через настоящий браузер.

Он поднимает локальный FastAPI search gateway и Streamable HTTP MCP-сервер. При первом запуске пакет сам создаёт изолированный Python venv, ставит зависимости, скачивает Chromium через Playwright и открывает:

MCP endpoint: http://127.0.0.1:8892/mcp
Search API: http://127.0.0.1:8891

Поиск идёт через Chromium по реальным страницам Google, Bing, Yahoo и DuckDuckGo, с fallback и дедупликацией ссылок.

Сделано в AI Platforms — внедрение приватных LLM и систем компьютерного зрения для предприятий, которым нужно, чтобы ИИ оставался в их собственной серверной.

Зачем browser search

У многих LLM-клиентов либо нет доступа к сети, либо есть только один внешний search API, либо нужно заранее заводить ключи и конфиги. browser-search-mcp сделан для локальных и приватных AI-сценариев, где:

Нужна одна команда npx, а не ручной деплой Python-сервиса.
Нужен поиск через реальные браузерные страницы, а не привязка к одному API.
Нужны несколько движков и fallback, когда один движок заблокирован, пустой или отдаёт мало результатов.
Нужно сначала быстро посмотреть snippets, а потом прочитать выбранные страницы через extract tools.

Node-пакет здесь только лаунчер. Основной runtime по умолчанию лежит в ~/.browser-search-mcp, поэтому npm-пакет остаётся маленьким.

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

npx browser-search-mcp

Первый запуск может занять несколько минут: ставятся Python-зависимости и скачивается Chromium. После запуска укажи в MCP-клиенте:

http://127.0.0.1:8892/mcp

Для MCP-клиентов, которым нужен stdio transport:

npx browser-search-mcp --stdio

Глобальная установка:

npm i -g browser-search-mcp
browser-search-mcp

Требования

Node.js 18+ для npx / npm.
Python 3.10+ в PATH.
Интернет при первом запуске для установки зависимостей и Chromium.
Около 500 MB на диске под изолированный runtime.
Windows, Linux или macOS.

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

Порты и путь runtime можно менять переменными окружения:

| Переменная | По умолчанию | Описание | |------------|--------------|----------| | BROWSER_SEARCH_MCP_HOME | ~/.browser-search-mcp | Runtime-директория для venv, install sentinel и логов. | | API_PORT | 8891 | Порт локального FastAPI search gateway. | | MCP_HOST | 127.0.0.1 | Host для MCP HTTP. | | MCP_PORT | 8892 | Порт MCP HTTP. | | SEARCH_API_TIMEOUT | 300 | Таймаут MCP → Search API, секунды. | | LOG_DIR | ~/.browser-search-mcp/logs | Директория логов Search API. |

Windows PowerShell:

$env:API_PORT = "8891"
$env:MCP_PORT = "8892"
npx browser-search-mcp

macOS / Linux:

API_PORT=8891 MCP_PORT=8892 npx browser-search-mcp

Инструменты

| Инструмент | Что делает | |------------|------------| | web_search | Один поисковый запрос: titles, URLs, snippets. Может дополнительно извлечь контент верхних результатов. | | deep_research | Раунд исследования по 1-10 запросам, выбранным моделью. Возвращает сгруппированные результаты. | | extract_webpage | Извлекает читаемый текст одной известной страницы. | | extract_webpages | Извлекает читаемый текст до 20 выбранных URL. |

Модель должна выбрать движок:

auto
google
bing
yahoo
duckduckgo
yandex
mailru

При engine=auto сервер пробует движки по очереди и добирает уникальные ссылки до нужного количества результатов.

HTTP API

Пакет также открывает обычный HTTP API на http://127.0.0.1:8891.

Поиск:

curl -X POST http://127.0.0.1:8891/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"Python asyncio tutorial","num_results":5,"engine":"auto","extract_content":false}'

Извлечение страницы:

curl -X POST http://127.0.0.1:8891/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","max_length":4000}'

Прочие endpoints:

| Endpoint | Описание | |----------|----------| | GET /api/health | Health check. | | GET /api/search/simple?q=...&n=3&engine=duckduckgo | Простой GET-поиск. | | GET /api/tools | Tool definitions в стиле OpenAI. | | GET /api/tools/openrouter | Tool definitions для OpenRouter. | | GET /docs | Swagger UI. |

Интеграции

Пакет запускает Streamable HTTP MCP-сервер. В любом MCP-клиенте, который умеет remote/HTTP MCP servers, укажи:

http://127.0.0.1:8892/mcp

Для локальных stdio MCP-записей, например в OpenCode:

{
  "mcp": {
    "browser-search-mcp": {
      "type": "local",
      "command": ["npx", "-y", "browser-search-mcp", "--stdio"],
      "enabled": true,
      "timeout": 1800000
    }
  }
}

Типовой порядок:

Запусти сервер:
```
npx browser-search-mcp
```
Добавь http://127.0.0.1:8892/mcp в список MCP servers клиента.
Включи сервер в настройках tools конкретного чата.
Попроси модель найти, проверить, исследовать или прочитать страницу.

Для llama.cpp Web UI включи MCP proxy в llama-server, добавь URL выше в MCP Servers и включи сервер в меню tools нужного чата.

Пример сценария в чате

Используй MCP browser-search-mcp. Найди последние release notes Playwright Python с engine=auto, выбери самые сильные источники, потом прочитай официальную страницу релиза и кратко перечисли breaking changes.

Типичная последовательность:

web_search с точным запросом и engine=auto.
Повторный web_search с другим движком, если результатов мало.
extract_webpage для официальной документации или release page.
Финальный ответ с опорой на источники.

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

MCP client ── Streamable HTTP ──► MCP server (:8892/mcp)
                                      │
                                      ▼
                              Search API (:8891)
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
          Chromium search pages              Page fetch + extraction
 Google / Bing / Yahoo / DDG / Yandex / Mail.ru  Playwright + trafilatura

API запускает Chromium headless через Playwright. DOM поисковой выдачи парсится в title, URL и snippet. Извлечение страниц использует Chromium для загрузки и trafilatura / BeautifulSoup для получения читаемого текста.

Безопасность и приватность

Запросы и извлечённый контент проходят через твой локальный MCP-клиент и локальный runtime.
При первом запуске пакет скачивает Python-зависимости и Chromium.
Поисковики и сайты видят запросы с твоей машины.
В пакете нет API-ключей и hosted-search credentials.
Runtime-файлы лежат в ~/.browser-search-mcp, если путь не переопределён.
Это локальная browser automation, а не анонимайзер.

Разработка

Состав npm-пакета:

bin/
  cli.js              Node launcher: bootstrap venv + запуск API/MCP
api/
  server.py           FastAPI browser search gateway
  mcp_server.py       Streamable HTTP MCP bridge
  requirements.txt    Python-зависимости runtime

Локальные проверки:

node --check bin/cli.js
python -m py_compile api/server.py api/mcp_server.py
npm pack --dry-run

About AI Platforms / О компании AI Platforms

AI Platforms — Russian systems integrator specialising in on-premises AI: private LLM/RAG stacks (DeepSeek, Qwen, Kimi, GLM), computer-vision for quality control and safety, AI chatbots and autonomous agents, 3D digital avatars, and GPU infrastructure. We deploy AI systems that stay inside our clients' server rooms — not in someone else's cloud.

AI Platforms — российский системный интегратор приватного ИИ: связки LLM/RAG (DeepSeek, Qwen, Kimi, GLM) на собственном железе клиента, компьютерное зрение для контроля качества и безопасности, ИИ-чат-боты и автономные агенты, 3D digital-аватары, GPU-инфраструктура. ИИ-системы остаются в серверной клиента, а не в чужом облаке.

Web: https://aiplatforms.ru/
E-mail: [email protected]
Tel: +7 (812) 987-70-07
Address: 196006, St. Petersburg, Mitrofan'evskoe Shosse 29A, office 213

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

English

Why browser search

Quick start

Requirements

Configuration

Tools

HTTP API

Integrations

Example chat workflow

How it works

Security and privacy

Development

Русский

Зачем browser search

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

Требования

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

Инструменты

HTTP API

Интеграции

Пример сценария в чате

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

Безопасность и приватность

Разработка

About AI Platforms / О компании AI Platforms

License