Google Ads MCP

Google Ads MCP es un servidor MCP local, de solo lectura y centrado en la seguridad, además de un plugin de Codex, para inspeccionar cuentas de Google Ads. La versión 0.1.0 expone un conjunto acotado de herramientas de inventario, informes, metadatos, historial de cambios y GAQL seguro. No contiene capacidades de escritura, carga, programación, eliminación, optimización ni transporte alojado.

La distribución pública de Python se denomina google-ads-operator-mcp. El producto y el comando siguen siendo Google Ads MCP y google-ads-mcp.

Límite de seguridad

• Toda solicitud limitada a una cuenta especifica tanto un perfil como un ID de cliente.

• Las credenciales de Google permanecen en Application Default Credentials o en un google-ads.yaml explícito de solo propietario, fuera del repositorio.

• accounts.json solo puede contener el nombre de una variable de entorno para el token de desarrollador, nunca el propio token.

• allowWrites debe ser false; cualquier otro valor se rechaza.

• El adaptador de producción solo construye GoogleAdsService, CustomerService y GoogleAdsFieldService.

• Una herramienta recibe filas normalizadas, nunca un cliente de Google ni un envoltorio de respuesta sin procesar.

• El modo MCP reserva stdout para JSON-RPC. Los diagnósticos y los códigos de error saneados se envían a stderr.

Lee SECURITY.md, PRIVACY.md y el modelo de amenazas antes de conectar una cuenta de producción.

Related MCP server: merchant-center-mcp

Requisitos

• Python 3.11, 3.12 o 3.13

• uv

• Acceso a la API de Google Ads con un token de desarrollador

• ADC, o un google-ads.yaml de solo propietario almacenado por separado

Sigue las guías oficiales de Google para el token de desarrollador, la configuración del cliente de Python y Application Default Credentials.

Configuración local

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

Después del lanzamiento público, la CLI independiente también se puede instalar con uv tool install google-ads-operator-mcp==0.1.0. Utiliza el archivo del plugin de la versión publicada, no una copia del árbol de fuentes, para la puerta de aceptación final del plugin limpio.

Edita ~/.config/google-ads-mcp/accounts.json, sustituye los ID de cuenta públicos y restaura los permisos de solo propietario:

Expón GOOGLE_ADS_DEVELOPER_TOKEN desde tu gestor de secretos local sin poner su valor en el repositorio ni en el historial del shell y, a continuación, ejecuta:

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

No pegues el token de desarrollador, el token de actualización de OAuth, el secreto de cliente, el JSON de ADC ni el contenido de YAML en este repositorio, en un issue, en una transcripción de terminal ni en un chat.

Configuración

La precedencia de la configuración es --config, luego GOOGLE_ADS_MCP_CONFIG y después ~/.config/google-ads-mcp/accounts.json.

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

Para un YAML de cliente de Google existente, usa {"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"}. Las rutas relativas y los enlaces simbólicos se rechazan. El servidor nunca busca credenciales YAML en el directorio de trabajo ni en el repositorio.

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

Herramientas MCP

La superficie fija de v0.1 es:

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

Las listas tipadas devuelven un máximo de 200 elementos por página. Una única lectura de Google está limitada a 1.000 filas normalizadas. Los cursores de cinco minutos están vinculados al perfil y a la solicitud exacta, con un máximo de 20 cursores activos por perfil. El GAQL seguro no tiene cursor y requiere un único SELECT sin comentarios, un recurso no sensible y LIMIT 1..1000.

Consulta docs/tools.md para conocer los parámetros, la semántica de evidencia y el comportamiento de los informes.

Plugin de Codex

La raíz del repositorio es la raíz del plugin. .mcp.json invoca a ./bin/google-ads-mcp-launcher, que solo ejecuta el entorno uv congelado a través de stdio. La habilidad implícita google-ads-operator trata todas las cadenas de cuenta como datos no fiables y nunca propone herramientas de mutación no disponibles.

El repositorio no crea ni modifica deliberadamente ninguna entrada de marketplace personal. La instalación desde el archivo de la versión publicada se valida por separado durante la aceptación.

Verificación

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

La verificación automatizada no es lo mismo que la aceptación con una cuenta real. Las puertas de aceptación de la cuenta de prueba y de solo lectura en producción descritas en docs/acceptance.md siguen siendo obligatorias antes de v0.1.0.

Licencia

Apache-2.0. Google Ads es una marca comercial de Google LLC. Este proyecto es independiente y no cuenta con el respaldo de Google.