common-crawl-mcp

MCP-сервер и CLI для запросов к Common Crawl — открытому корпусу веба, на котором учат языковые модели.

Отвечает на вопрос «виден ли сайт для ИИ»: сколько его страниц попало в корпус, какие разделы, как это менялось, и что видит модель, читая конкретную страницу.

Работает через AWS Athena поверх колоночного индекса (cc-index), а не через публичный API Common Crawl — тот регулярно отдаёт 504. Запрос по домену стоит около $0.00005.

Установка

uv tool install git+https://github.com/nikolaymokh-dev/common-crawl-mcp

Нужны AWS-креды с доступом к Athena, Glue и чтением бакета commoncrawl. Берутся из ~/.aws обычным способом (AWS_PROFILE, AWS_REGION; по умолчанию us-east-1).

CLI

ccq example.com                          # страниц в свежем кравле
ccq example.com --dynamics               # динамика по 18 последним кравлам
ccq example.com --locales --sections     # разбивка по языкам и разделам
ccq example.com --compare example.org,example.net
ccq example.com --errors                 # 404/301/5xx, которые получил краулер
ccq example.com --robots                 # robots.txt глазами краулера
ccq --discover de --min-pages 100        # домены зоны .de
ccq --zone-suffixes uk                   # co.uk / org.uk / gov.uk ...
ccq --list-crawls

Любую команду можно получить в JSON: --json.

MCP

claude mcp add common-crawl -- uvx --from git+https://github.com/nikolaymokh-dev/common-crawl-mcp common-crawl-mcp

Тулы

Тул	Зачем
cc_presence	Сколько страниц домена в кравле
cc_dynamics	Динамика по кравлам — основа для любых выводов
cc_compare	Несколько доменов одним сканом
cc_locales	Разбивка по языковым префиксам пути
cc_sections	Топ разделов: где охват проседает
cc_urls	Конкретные URL + координаты в архиве
cc_duplicates	Страницы-дубли (одинаковый content_digest)
cc_errors	Не-200 ответы у домена
cc_robots	robots.txt в момент обхода
cc_discover	Домены по зоне и/или подстроке
cc_zone_suffixes	Суффиксы внутри зоны
cc_fetch_text	Текст страницы из архива — то, что читает модель
cc_crawls	Список доступных кравлов

Что стоит знать

Ноль страниц ≠ сайта нет. Охват Common Crawl заметно скачет между кравлами: сайт, стабильно дающий сотни страниц, может провалиться до единиц. Любой вывод делается по cc_dynamics, а не по одному снимку.

Поиск по зоне почти бесплатен. Индекс отсортирован по url_surtkey — имени хоста задом наперёд, — поэтому домены одной зоны лежат в файлах подряд, и Athena пропускает всё остальное. Замерено на CC-MAIN-2026-30: .uz — 0.28 MB скана на 7 954 домена, .de — 23 MB на 2 075 692 домена.

Поиск по подстроке — нет. host_contains не может воспользоваться этой сортировкой, поэтому без указания зоны он читает колонку хостов по всему кравлу. Тул это запрещает, пока не передашь allow_full_scan=True. Заодно зона отсекает ложные совпадения: короткая подстрока по всему вебу цепляет случайные домены из чужих зон, внутри одной зоны — нет.

Составные зоны. tld='uk' захватывает и example.uk, и example.co.uk. Нужен конкретный сегмент — фильтруй registry_suffix='co.uk'. Посмотреть, что вообще есть в зоне, — cc_zone_suffixes.

Стоимость возвращается вместе с данными. В каждом ответе есть scanned_mb и cost_usd. Athena billing округляет запрос вверх до 10 MB.

Разработка

uv sync --extra dev
uv run pytest              # юнит-тесты, сети не требуют

Структура: athena.py — транспорт, crawls.py — какие кравлы есть, queries.py — построители SQL (чистые функции, тестируются без AWS), api.py — операции, warc.py — извлечение текста, cli.py и server.py — две обёртки над api.

Лицензия

MIT