webscout-mcp

Инструменты веб-поиска и загрузки страниц для ИИ-агентов в виде MCP-сервера. Поиск, загрузка, обход сайтов и извлечение структурированных данных из интернета — без API-ключей, без платы за каждый запрос, всё остаётся на вашей машине.

Установка

pip install webscout-mcp

Требуется Python 3.10+.

Related MCP server: Crawl4AI RAG MCP Server

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

Добавьте в конфигурацию вашего MCP-клиента (Claude Code, Cursor, Codex и т.д.):

{
  "mcpServers": {
    "webscout": {
      "command": "webscout-mcp",
      "args": []
    }
  }
}

Вот и всё. Ваш агент получает шесть инструментов:

• web_search — поиск через Bing с автоматическим переходом на HTML-версию DuckDuckGo, ключ не нужен

• web_fetch — загрузка страницы и извлечение основной статьи (markdown/text/html)

• web_crawl — параллельный обход BFS с ограничениями по глубине и количеству страниц, учитывает robots.txt

• web_extract — извлечение структурированных данных с помощью CSS-селекторов, атрибутов и регулярных выражений

• cache_stats — просмотр локального кэша

• cache_clear — очистка кэша

Использование CLI

Помимо работы в качестве MCP-сервера, webscout-mcp можно использовать напрямую из командной строки:

# Search the web (outputs JSON)
webscout-mcp search "python async libraries" --max-results 5

# Fetch a page (raw content)
webscout-mcp fetch https://example.com --extract --format markdown --raw

# Crawl a site
webscout-mcp crawl https://example.com --depth 2 --pages 10

# Start MCP server (default if no command given)
webscout-mcp serve --transport stdio

Примеры использования

Поиск

web_search(query="best python async libraries", max_results=5)

Возвращает структурированные результаты с заголовком, URL, сниппетом и указанием бэкенда, обработавшего запрос (bing или duckduckgo). Если Bing не срабатывает или меняет свою разметку, движок автоматически переключается на HTML-версию DuckDuckGo — никакой настройки не требуется.

Загрузка страницы

web_fetch(url="https://example.com", extract=true, output_format="markdown")

extract=true запускает trafilatura (с автоматическим запасным вариантом на readability-lxml), чтобы убрать навигацию, рекламу и боковые панели — вы получаете чистое содержимое статьи, а не сырой HTML.

Извлечение структурированных данных

web_extract(
  url="https://example.com/products",
  rules='[
    {"name": "titles", "selector": ".product h2", "multiple": true},
    {"name": "prices", "selector": ".price", "regex": "\\$([\\d.]+)", "multiple": true},
    {"name": "links", "selector": "a.product", "attribute": "href", "multiple": true}
  ]'
)

Каждое правило поддерживает selector, attribute, multiple, regex и default.

Обход сайта

web_crawl(seed_url="https://example.com", max_depth=2, max_pages=10, concurrency=5)

Страницы каждого уровня глубины загружаются параллельно (управляется параметром concurrency, по умолчанию 5). Краулер по умолчанию учитывает robots.txt — запрещённые URL пропускаются и учитываются в skipped_robots. Ограничение тем же доменом включено по умолчанию.

Использование в качестве Python-библиотеки

import asyncio
from webscout_mcp import Config, Fetcher, SearchEngine

async def main():
    config = Config.from_env()
    config.ensure_dirs()

    fetcher = Fetcher(config)
    result = await fetcher.fetch("https://example.com", extract=True)
    print(result.title)
    print(result.content[:500])
    await fetcher.close()

    search = SearchEngine(config)
    results = await search.search("python async", max_results=5)
    for r in results:
        print(f"{r.position}. {r.title} - {r.url} ({r.backend})")
    await search.close()

asyncio.run(main())

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

• Поиск сначала пробует Bing, затем HTML-версию DuckDuckGo — оба через прямой HTTP-скрапинг, без API-ключа. Результаты кэшируются по каждому запросу.

• Загрузка использует httpx с повторами по экспоненциальной задержке (все ошибки httpx + HTTP 5xx), ограничением скорости запросов по алгоритму token bucket для каждого домена и лимитом 5 МБ на объём контента.

• Извлечение контента использует trafilatura в качестве основного механизма и readability-lxml как автоматический запасной вариант — те же библиотеки, на которых работают многие сервисы отложенного чтения.

• Кэширование — это SQLite с TTL и ограничением размера; старые записи удаляются автоматически. Повторные загрузки и поисковые запросы ничего не стоят.

• Обход сайтов — это параллельный BFS с настраиваемыми глубиной, количеством страниц, степенью параллелизма, ограничением по домену и соблюдением robots.txt. Используется сырой HTML из первоначальной загрузки, чтобы не загружать каждую страницу дважды.

• Поддержка прокси — маршрутизация всех HTTP/HTTPS-запросов через прокси с помощью конфигурации или переменных окружения.

• Логирование — структурированное, настраивается через WEBSCOUT_LOG_LEVEL (DEBUG/INFO/WARNING/ERROR); установите WEBSCOUT_LOG_JSON=1 для вывода в формате JSON.

Всё работает локально. Никакие данные не покидают вашу машину.

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

Все параметры имеют разумные значения по умолчанию. Их можно переопределить через переменные окружения (префикс WEBSCOUT_), TOML-файл конфигурации или флаги CLI.

Файл конфигурации

Создайте ~/.config/webscout/config.toml (или $XDG_CONFIG_HOME/webscout/config.toml):

[cache]
ttl = 7200
max_size_mb = 512

[fetch]
timeout = 15.0
max_retries = 3

[proxy]
http = "http://proxy:8080"
https = "http://proxy:8080"

[search]
max_results = 10
backends = ["bing", "duckduckgo"]

[crawler]
max_depth = 2
max_pages = 20
concurrency = 5
respect_robots = true

[logging]
level = "WARNING"
json = false

Переменные окружения имеют приоритет над значениями из файла конфигурации.

Переменные окружения

Флаги CLI имеют приоритет над переменными окружения:

webscout-mcp --cache-ttl 3600 --cache-dir /tmp/webscout serve

Транспорты

# stdio (default - works with Claude Code, Cursor, etc.)
webscout-mcp

# SSE (for remote or browser-based clients)
webscout-mcp serve --transport sse --host 0.0.0.0 --port 8000

Журнал изменений

0.3.0

• Поддержка TOML-файла конфигурации: настройка через ~/.config/webscout/config.toml в дополнение к переменным окружения

• Поддержка HTTP/HTTPS-прокси: маршрутизация всех запросов через прокси

• Двойное извлечение контента: trafilatura как основной механизм, readability-lxml как автоматический запасной вариант

• Дедупликация результатов поиска: повторяющиеся URL удаляются, позиции перенумеровываются

• Поиск с учётом региона: параметр region теперь действительно передаётся в Bing и DuckDuckGo

• Производительность краулера: устранена двойная загрузка каждой страницы — обход стал быстрее в ~2 раза

• Улучшенная логика повторов: повторные попытки при всех ошибках httpx и HTTP 5xx

• Исправлено определение content-type: корректное определение HTML/XML

0.2.0

• Многобэкендный поиск: Bing + HTML-версия DuckDuckGo с автоматическим переключением

• Параллельный краулер с настраиваемой степенью параллелизма

• Соблюдение robots.txt (настраивается, включено по умолчанию)

• Подкоманды CLI: search, fetch, crawl, serve

• Структурированное логирование с консольным и JSON-форматтерами

• Собственная иерархия исключений для более качественной обработки ошибок

• Новые параметры: WEBSCOUT_SEARCH_BACKENDS, WEBSCOUT_CRAWLER_CONCURRENCY, WEBSCOUT_RESPECT_ROBOTS

0.1.0

• Первый выпуск: web_search, web_fetch, web_crawl, web_extract, cache_stats, cache_clear

• Кэш SQLite с TTL и вытеснением по размеру

• Ограничение скорости по алгоритму token bucket для каждого домена

• Повторы с экспоненциальной задержкой

• Извлечение контента через trafilatura

Разработка

git clone https://github.com/wxs-lang/webscout-mcp.git
cd webscout-mcp
pip install -e ".[dev]"
pytest

Лицензия

MIT