Неофициальный MCP-сервер для Google Trends

⚠️ Неофициальный проект. Не связан с Google, не одобрен и не поддерживается Google. У Google Trends нет общедоступного API, поэтому этот сервер читает те же публично доступные конечные точки, которые использует сайт trends.google.com (через trendspy) — а это значит, что Google может в любой момент ограничить скорость или сломать его без предупреждения. Используйте на свой страх и риск и прочитайте Ограничения, прежде чем полагаться на него.

Сервер Model Context Protocol, который даёт ИИ-ассистентам — Claude, ChatGPT, Cursor или любому MCP-клиенту — доступ к данным Google Trends: интерес к поиску с течением времени, разбивка по регионам, трендовые запросы и идеи ключевых слов.

Работает как удалённый MCP-сервер (streamable HTTP), предназначенный для Google Cloud Run — вы размещаете его в своём проекте Google Cloud и подключаете к своему ИИ-ассистенту. Также работает локально через stdio.

Подключение к вашему ИИ-ассистенту

После развёртывания (см. Настройка) у вас будет URL конечной точки вида https://<ваш-сервис>.run.app/<секрет>/mcp. Все инструменты доступны только для чтения.

Claude (веб/десктоп): Настройки → Connectors → Add custom connector → вставьте URL. Работает на тарифах Pro, Max, Team и Enterprise.

ChatGPT (веб): включите Developer mode (Настройки → Apps → Advanced settings), затем Настройки → Apps → Create, вставьте URL как конечную точку MCP-сервера, выберите No authentication (контроль доступа — это секрет в URL), нажмите Scan tools → Create. Пользовательские MCP-коннекторы требуют платного тарифа; на Pro коннекторы ограничены инструментами только для чтения — а у этого сервера только такие, так что всё работает.

Claude Code / Cursor / другие MCP-клиенты: подойдёт любой клиент, поддерживающий удалённый MCP через streamable HTTP, например claude mcp add --transport http google-trends <URL>. Для локальных/stdio-настроек см. docs/setup-advanced.md.

Related MCP server: youtube-trends-mcp

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

AI assistant (Claude · ChatGPT · Cursor · any MCP client)
   │  MCP over streamable HTTP, at https://<cloud-run-url>/<secret>/mcp
   ▼
server.py — FastMCP tool layer (stateless, JSON responses)
   │  TrendsBackend interface (swappable, see backends/)
   ▼
backends/trendspy_backend.py
   │  1. TTL cache — identical queries answered from memory
   │     (12 h series · 15 min trending · 24 h autocomplete)
   │  2. Circuit breaker — after a 429: cooldown, fail fast with
   │     a clear "retry in Ns" message (no hammering Google)
   │  3. One upstream call at a time, ≥3 s apart
   ▼
Google's public endpoints
   ├─ trends.google.com (unofficial, same as the website uses)
   └─ suggestqueries.google.com (Autocomplete, for keyword_ideas)

Контроль доступа — это случайный секретный сегмент пути в URL (генерируется при развёртывании, хранится в gitignored-файле .mcp_secret) — используется потому, что большинство интерфейсов пользовательских коннекторов чат-клиентов (Claude, ChatGPT) не могут отправлять заголовки аутентификации. Сервис Cloud Run намеренно ограничен одним экземпляром: один экземпляр = один IP и один общий кэш, что делает ограничение скорости Google предсказуемым. Он масштабируется до нуля в простое, так что хостинг практически бесплатен при личном использовании.

Инструменты

Бэкенды данных

Слой данных заменяемый (см. backends/):

• trendspy (по умолчанию) — использует trendspy, который общается с теми же неофициальными конечными точками, что и сайт Trends. Бесплатно, без API-ключа, но с ограничением скорости на IP и может сломаться, если Google изменит свои конечные точки.

• official (заглушка) — для официального API Trends от Google (альфа), который доступен по заявке. Подключите backends/official_backend.py, как только Google предоставит доступ вашему проекту, затем установите TRENDS_BACKEND=official. Контракт MCP-инструментов остаётся идентичным.

⚠️ Значения из Google Trends — это относительный интерес к поиску (0–100 в рамках каждого запроса), а не абсолютные объёмы поиска.

Настройка

Два руководства, выбирайте по скорости:

• Руководство для начинающих — никогда не пользовались терминалом или Google Cloud? Полное пошаговое руководство с нуля, ~15 минут.

• Продвинутое руководство — опытный пользователь? Клонируйте → ./deploy.sh → подключите; плюс локальный режим stdio, справочник по конфигурации и заметки по архитектуре.

Развёртывание в Cloud Run (краткая версия)

gcloud auth login
./deploy.sh YOUR_PROJECT_ID europe-west1

Скрипт включает необходимые API, собирает контейнер с помощью Cloud Build, развёртывает с масштабированием до нуля (≈ бесплатно при низком использовании) и выводит вашу MCP-конечную точку:

https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Случайный сегмент пути <секрет> — это токен доступа: сервис технически публичен, но недоступен без полного URL. Держите его в тайне и повторно запустите развёртывание с новым секретом для его ротации.

Подключите своего ИИ-ассистента

См. Подключение к вашему ИИ-ассистенту выше для Claude и ChatGPT. Claude Code:

claude mcp add --transport http google-trends https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Локальный запуск

pip install -r requirements.txt
python server.py
# MCP endpoint at http://localhost:8080/mcp

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

Ограничения и известные проблемы

Прочитайте это, прежде чем полагаться на сервер — это структурные ограничения, а не баги:

1. Неофициальный источник данных. Не существует публичного API Google Trends (официальный API Google — альфа и только по приглашениям). Этот сервер использует собственные конечные точки сайта, которые Google может изменить или заблокировать в любой момент. Если Google что-то изменит, сервер перестанет работать, пока trendspy не догонит — именно это случилось со старой библиотекой pytrends в 2025 году.

2. related_queries и related_topics фактически мертвы. Google устанавливает почти нулевую квоту на эти две конечные точки «виджетов» для автоматизированных (не браузерных) клиентов. Лимит привязан к отпечатку клиента, а не к IP — прокси, VPN и локальный запуск не помогают. Ожидайте, что эти инструменты чаще всего будут падать при первом вызове; сообщение об ошибке объясняет это и указывает на keyword_ideas (Google Autocomplete), который является надёжной альтернативой для исследования ключевых слов.

3. Ограничение скорости на всё остальное. Рабочие конечные точки (интерес с течением времени, по регионам, тренды) также ограничены по скорости на IP. Всплески запросов вызывают HTTP 429. Меры сервера (ниже) делают это редким при обычном использовании, но интенсивные автоматические запросы упрутся в стену.

4. Относительные значения, а не объёмы. Все числа Trends — это 0–100 в рамках каждого запроса (100 = пик для данного набора терминов/периода/гео). Это не абсолютные объёмы поиска и они не сопоставимы между разными запросами.

5. Компромисс со свежестью. Результаты кэшируются (12 ч для данных серий, 15 мин для трендов, 24 ч для автодополнения), чтобы оставаться в рамках ограничений скорости — вы можете видеть слегка устаревшие данные по замыслу.

6. Один экземпляр. Развёртывается с --max-instances 1, поэтому это для личного/небольшого командного использования, а не для высоконагруженного продакшн-трафика.

Ограничения скорости и как сервер спроектирован вокруг них

Google ограничивает скорость неофициальных конечных точек Trends. Сервер смягчает это по слоям:

• TTL-кэш — идентичные запросы обслуживаются из памяти (~12 ч для данных серий, 15 мин для трендов, 24 ч для автодополнения) и никогда не обращаются к Google дважды.

• Интервалы + сериализация — один вызов вышестоящего сервиса за раз, с паузой TRENDS_REQUEST_DELAY (по умолчанию 3 с) между вызовами.

• Повтор + автоматический выключатель — одна мягкая попытка при 429, затем период охлаждения (120 с), в течение которого новые запросы быстро завершаются с понятным сообщением «повторите через N секунд» вместо долбёжки Google. Кэшированные запросы продолжают работать во время охлаждения.

• Правила использования передаются ИИ-клиенту через MCP-инструкции: группируйте до 5 терминов в один вызов interest_over_time, планируйте вызовы вместо их разброса, никогда не повторяйте автоматически ошибку ограничения скорости.

• Реальность related_queries / related_topics: Google сократил квоту на эти две конечные точки виджетов до почти нуля для автоматизированных (не браузерных) клиентов — это привязано к отпечатку, поэтому прокси и смена IP не помогают. Ожидайте их падения; ошибка объясняет это. Используйте keyword_ideas (Google Autocomplete) для исследования ключевых слов — это быстро, надёжно и не привязано к квоте Trends.

--max-instances 1 в скрипте развёртывания намерен: один экземпляр = один IP и один общий кэш = предсказуемое ограничение скорости.

Советы пользователям

Просите сравнения за один раз («сравни A vs B vs C в PT за 12 месяцев» → один вызов API), а не по одному термину. Повторные недавние вопросы бесплатны (кэш). Если вы получили сообщение об охлаждении, просто подождите указанные секунды — не спамьте повторами. Для вопросов «что люди ищут вокруг X» просите идеи ключевых слов, а не связанные запросы.

Заметки по безопасности

Всё в этом репозитории общее — нет учётных данных, ключей, ID проектов или личных данных. Две вещи остаются локальными на вашей машине и никогда не должны быть закоммичены:

• .mcp_secret — случайная строка в вашем URL конечной точки. Это единственное, что мешает посторонним вызывать ваш развёрнутый сервер, поэтому относитесь к ней как к паролю. deploy.sh генерирует её при первом запуске и хранит здесь, чтобы повторные развёртывания использовали тот же URL. Она в gitignore. (Она не связана с GitHub — это не токен GitHub и у неё нет доступа к вашему аккаунту.)

• ID вашего проекта Google Cloud — передаётся как аргумент командной строки в deploy.sh, никогда не записывается ни в один файл в репозитории.

Для ротации секрета (например, если URL утёк): удалите .mcp_secret, повторно запустите ./deploy.sh <PROJECT_ID> и обновите URL в настройках коннектора вашего ИИ-ассистента. Старый URL перестанет работать немедленно.

Перед первым пушем убедитесь, что ничего чувствительного не в индексации:

git status --short          # .mcp_secret and .env must NOT appear
git check-ignore -v .mcp_secret

Отказ от ответственности

Неофициальный общественный проект; не связан с Google, не одобрен и не поддерживается Google. «Google Trends» и «Google» — товарные знаки Google LLC, используемые здесь только для описания того, к чему подключается программное обеспечение. Данные Trends получаются через публично доступные конечные точки; вы несёте ответственность за использование в соответствии с условиями обслуживания Google и на свой страх и риск. Никаких гарантий любого рода — конечные точки могут перестать работать в любой момент.

Лицензия

MIT