Keyword Research MCP

Keyword Research MCP — это легковесный локальный MCP-сервер для получения и нормализации данных планирования ключевых слов Google Ads. Он находится в активной разработке; текущий репозиторий содержит исполняемую основу проекта, а также типизированный, протестированный исследовательский интерфейс и производственный адаптер Google Ads. Регистрация инструментов MCP, описанная в плане реализации, ещё создаётся.

Платная конкуренция в Google Ads описывает активность рекламодателей. Этот проект не представляет её как сложность органического ранжирования и не вычисляет составной показатель ключевого слова.

Требования

• Python 3.10–3.14

• uv

Учётные данные Google Ads не нужны для тестов. Они требуются, когда производственный адаптер подключается к Google Ads.

Related MCP server: Google Ads MCP Server

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

Производственный адаптер использует google-ads==31.2.0 и явно выбирает API Google Ads v25. Настройте ровно одного целевого клиента и один метод аутентификации. Идентификаторы клиентов могут содержать дефисы; они нормализуются в памяти.

Для пользовательского OAuth задайте:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="987-654-3210" # optional manager account
export GOOGLE_ADS_CLIENT_ID="client-id-placeholder"
export GOOGLE_ADS_CLIENT_SECRET="client-secret-placeholder"
export GOOGLE_ADS_REFRESH_TOKEN="refresh-token-placeholder"

Для сервисного аккаунта опустите три параметра пользовательского OAuth и задайте:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/service-account.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="ads-user@example.test" # optional

В качестве альтернативы укажите GOOGLE_ADS_CONFIGURATION_FILE_PATH на локальный google-ads.yaml:

developer_token: developer-token-placeholder
customer_id: "123-456-7890"
login_customer_id: "987-654-3210"
client_id: client-id-placeholder
client_secret: client-secret-placeholder
refresh_token: refresh-token-placeholder

Дополнительные параметры процесса: KEYWORD_RESEARCH_CACHE_CAPACITY (по умолчанию 128) и KEYWORD_RESEARCH_LOG_LEVEL (по умолчанию INFO). Файлы учётных данных, google-ads.yaml и файлы .env игнорируются Git.

Установка и запуск

uv sync
uv run keyword-research-mcp

Команда работает через stdio, поэтому она молча ожидает MCP-клиента и записывает сообщения протокола только в стандартный вывод.

Разработка

Запустите тот же контроль качества, что используется в CI:

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build

См. план реализации для предполагаемых контрактов инструментов, архитектуры, этапов поставки и границ продукта.

Лицензия

MIT