Keyword Research MCP

Keyword Research MCP es un servidor MCP local ligero para recuperar y normalizar evidencia de planificación de palabras clave de Google Ads. Está en desarrollo activo; el repositorio actual contiene la base ejecutable del proyecto, además de la interfaz de investigación tipada y probada y el adaptador de producción de Google Ads. El registro de herramientas MCP descrito en el plan de implementación aún se está construyendo.

La competencia pagada en Google Ads describe la actividad de los anunciantes. Este proyecto no la presenta como dificultad de ranking orgánico ni calcula una puntuación compuesta de palabras clave.

Requisitos

• Python 3.10 a 3.14

• uv

No se necesitan credenciales de Google Ads para las pruebas. Se requieren cuando el adaptador de producción se conecta a Google Ads.

Related MCP server: Google Ads MCP Server

Configuración de Google Ads

El adaptador de producción utiliza google-ads==31.2.0 y selecciona explícitamente la API de Google Ads v25. Configure exactamente un cliente objetivo y un método de autenticación. Los ID de cliente pueden contener guiones; se normalizan en memoria.

Para OAuth de usuario, establezca:

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"

Para una cuenta de servicio, omita los tres ajustes de OAuth de usuario y establezca:

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

Alternativamente, apunte GOOGLE_ADS_CONFIGURATION_FILE_PATH a un google-ads.yaml local:

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

Los ajustes opcionales del proceso son KEYWORD_RESEARCH_CACHE_CAPACITY (por defecto 128) y KEYWORD_RESEARCH_LOG_LEVEL (por defecto INFO). Los archivos de credenciales, google-ads.yaml y los archivos .env son ignorados por Git.

Configuración y ejecución

uv sync
uv run keyword-research-mcp

El comando se ejecuta sobre stdio, por lo que espera silenciosamente a un cliente MCP y escribe mensajes de protocolo solo en la salida estándar.

Desarrollo

Ejecute la misma compuerta de calidad utilizada en CI:

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

Consulte el plan de implementación para conocer los contratos de herramientas previstos, la arquitectura, las fases de entrega y los límites del producto.

Licencia

MIT