aapl-ads-mcp

Un servidor MCP que conecta a Claude (y a cualquier cliente compatible con MCP) con la API v5 de Apple Search Ads.

Qué es esto

MCP (Model Context Protocol) es un estándar abierto que permite a los asistentes de IA llamar a herramientas externas. Este servidor implementa el transporte stdio de MCP y expone 9 herramientas de solo lectura que consultan tu cuenta de Apple Search Ads: campañas, grupos de anuncios, palabras clave e informes de rendimiento.

Lo instalas una vez, apuntas Claude Desktop hacia él y luego haces preguntas en lenguaje natural: "¿Qué palabras clave generaron más instalaciones el mes pasado?" o "Muéstrame las campañas con cero impresiones esta semana".

Related MCP server: tiktok-ads-mcp

Por qué

Los paneles oficiales de ASA son buenos para los humanos, pero no para el análisis ad-hoc o la generación de informes automatizados. Las alternativas MCP existentes son SaaS (entregas tus claves) o no tienen mantenimiento. Esta es una opción de código abierto y autohospedada que tú controlas.

Características

• list_orgs — verificar la autenticación, listar organizaciones accesibles

• list_campaigns — enumerar campañas, filtrar opcionalmente por estado

• list_ad_groups — grupos de anuncios para una campaña determinada

• list_keywords — palabras clave de segmentación con importes de puja y tipo de concordancia

• get_campaign_report — impresiones, toques, instalaciones, gasto, CPI, TTR por campaña

• get_ad_group_report — mismas métricas desglosadas por grupo de anuncios

• get_keyword_report — rendimiento por palabra clave con granularidad semanal/diaria/mensual

• get_search_terms_report — los términos de búsqueda reales que activaron tus anuncios (muy útil para el descubrimiento)

Todas las herramientas utilizan los últimos 30 días por defecto. Los informes admiten granularidad HOURLY, DAILY, WEEKLY y MONTHLY.

Limitaciones

• Solo lectura por diseño. No hay operaciones de escritura (crear, actualizar, pausar) en esta versión.

• Requiere acceso a la API de gestión de campañas de Apple Search Ads. Necesitas crear un usuario de API en tu cuenta de ASA y generar un par de claves ES256.

• Las métricas de instalación agregadas funcionan sin integración en la aplicación. tapInstalls, viewInstalls y los campos relacionados en los informes de ASA son poblados directamente por Apple Search Ads y no requieren ningún SDK en tu aplicación. AdServices / AdAttributionKit solo es necesario si deseas atribuir instalaciones a campañas específicas desde dentro de tu aplicación (por ejemplo, para la personalización de la incorporación).

• Organización única. El ID de la organización está fijado en la configuración. El cambio entre múltiples organizaciones no está implementado.

Configuración

1. Generar un par de claves ES256

Usa el comando moderno genpkey: produce directamente el formato PKCS#8, que es lo que requiere este servidor. El antiguo ecparam -genkey produce el formato SEC1 y causará un error al iniciar.

# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem

# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pem

Verifica que la clave privada comience con -----BEGIN PRIVATE KEY----- (no -----BEGIN EC PRIVATE KEY-----). Si comienza con la variante EC, conviértela:

openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pem

Almacena private-key.pem fuera de la raíz del repositorio si es posible (por ejemplo, ~/.ssh/asa-private-key.pem).

2. Crear un usuario de API en Apple Search Ads

1. Ve a ASA → Account Settings → User Management

2. Haz clic en Create User, elige el rol API Account Read Only para uso de solo lectura (recomendado para este servidor). API Campaign Manager también es válido y añade permisos de escritura si planeas extender el servidor con herramientas de escritura más adelante.

3. Ve a la pestaña API, haz clic en Create Client

4. Sube public-key.pem

5. Copia client_id, team_id y key_id de la pantalla de confirmación

6. Encuentra tu org_id en Account Settings → Overview

3. Clonar y compilar

git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build

4. Configurar Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aapl-ads": {
      "command": "node",
      "args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"],
      "env": {
        "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",

"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"

} }

} }

Nota: ASA_PRIVATE_KEY_PATH debe ser una ruta absoluta. La tilde (~) no es expandida por Node.js; usa la ruta completa.

Para despliegues en contenedores o en la nube donde montar un archivo no es práctico, establece ASA_PRIVATE_KEY con el contenido PEM en línea (preservando los saltos de línea). Si ambos están configurados, ASA_PRIVATE_KEY tiene prioridad.

Reinicia Claude Desktop. Pregunta "run health check" para verificar que el servidor esté conectado.

Ejemplos de uso

Estos son prompts en lenguaje natural que funcionan con Claude Desktop una vez que el servidor está en ejecución:

List my Apple Ads campaigns

Muéstrame el rendimiento de las campañas de los últimos 30 días

¿Qué palabras clave generaron instalaciones en mi campaña de marca la semana pasada?

¿Qué términos de búsqueda activaron mis anuncios el mes pasado? Enfócate en aquellos con impresiones pero sin instalaciones.

Compara el gasto semanal en todas las campañas para el primer trimestre de 2025

Muéstrame los grupos de anuncios en la campaña 1234567890 con sus importes de puja

## Development

```bash
npm run build      # compile TypeScript
npm test           # run test suite (Vitest)
npm run typecheck  # type-check without emitting
npm run lint       # Biome lint
npm run format     # Biome format (write)

Inspector MCP

Para depurar llamadas a herramientas de forma interactiva sin Claude Desktop:

npx @modelcontextprotocol/inspector node dist/index.js

Establece las variables de entorno en la interfaz de usuario del Inspector antes de conectar.

Hooks de pre-commit

Instala los hooks de lefthook localmente después de clonar:

npx lefthook install

Esto configura:

• gitleaks protect --staged — bloquea commits que contienen secretos

• Verificación de lint de Biome en archivos .ts preparados

• Verificación de tipos de TypeScript

Contribución

Consulta docs/ARCHITECTURE.md para obtener detalles técnicos: flujo de autenticación, diseño del cliente HTTP, patrón de herramientas, peculiaridades del esquema de informes y lecciones aprendidas de ASA v5 durante el desarrollo.

Los informes de errores y las solicitudes de extracción son bienvenidos.

Seguridad

• Nunca hagas commit de archivos .env o *.pem: ambos están en .gitignore

• Mantén private-key.pem fuera de la raíz del repositorio

• El token de acceso se mantiene solo en memoria, nunca se escribe en el disco

• Si sospechas que una clave ha sido expuesta, rótala en ASA → Account Settings → API

Licencia

MIT — consulta LICENSE.