Skip to main content
Glama
aapl-ads-mcp

aapl-ads-mcp

by andrealufino

aapl-ads-mcp

Node version License andrealufino/aapl-ads-mcp MCP server

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: Reddit Ads MCP Server

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.

Available Tools

9 tools
get_ad_group_reportA

Fetch performance metrics for ad groups within a specific Apple Search Ads campaign: impressions, taps, TTR, spend, CPI, installs (tap-through and view-through), and install rate. Requires ASA authentication; read-only. Use get_campaign_report for a campaign-level summary, or get_keyword_report for keyword-level detail. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), endDate, startDate, adGroupIds, +1 more.

get_campaign_reportA

Fetch performance metrics for Apple Search Ads campaigns: impressions, taps, tap-through rate (TTR), localSpend, avgCPT, avgCPM, tapInstalls, viewInstalls, totalInstalls, new downloads, redownloads, CPI, and install rate. Requires ASA authentication; read-only. Use get_ad_group_report or get_keyword_report for deeper breakdowns. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: startDate, endDate, granularity, campaignIds.

get_keyword_reportA

Fetch performance metrics for targeting keywords in a specific Apple Search Ads ad group: impressions, taps, TTR, spend, CPI, installs, and install rate broken down per keyword. Requires ASA authentication; read-only. Use get_search_terms_report to see the actual user queries that triggered these keywords. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

get_search_terms_reportA

Fetch the actual user search queries that triggered Apple Search Ads impressions, along with performance metrics per search term. Requires ASA authentication; read-only. Most useful for keyword discovery (finding new terms to add) and negation (finding irrelevant queries to exclude). Does not support granularity breakdown — returns aggregate totals per search term. Use get_keyword_report to see metrics for your configured targeting keywords instead. Defaults to the last 30 days.

Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.

healthA

Check if the aapl-ads-mcp server is running and reachable. Use this to verify the MCP connection before making API calls. No ASA authentication is required — returns server name, version, and current timestamp.

Inputs: no named parameters.

list_ad_groupsA

List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), limit, offset.

list_campaignsA

List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: status, limit, offset.

list_keywordsA

List targeting keywords for a specific Apple Search Ads ad group. Requires ASA authentication; read-only. Returns keyword metadata (text, match type BROAD/EXACT, bid amount, status) but not performance metrics — use get_keyword_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.

Inputs: campaignId (required), adGroupId (required), limit, offset.

list_orgsA

List all Apple Search Ads organizations accessible with the configured credentials. Requires ASA authentication. Use this to verify credentials are valid and to discover available org IDs before calling other tools. Returns org ID, name, currency, timezone, payment model, and assigned role names.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action: list_* for enumerating hierarchy levels, get_*_report for metrics at each level, get_search_terms_report for search queries, and health for server status. No two tools could be confused for the same task.

    Naming Consistency4/5

    Most tools follow the list_ or get_*_report pattern clearly separating metadata enumeration from report retrieval. The single deviation is 'health', which is a noun rather than a verb-prefixed action (e.g., check_health), making the pattern slightly inconsistent.

    Tool Count5/5

    Nine tools is well-scoped for a read-only Apple Search Ads data access server: four list tools for entity hierarchy, four report tools for metrics breakdowns, and a health check. Each tool serves a distinct need without redundancy.

    Completeness4/5

    The read-only surface covers the full object hierarchy (org → campaign → ad group → keyword) with list operations and corresponding report endpoints, including search terms. However, the complete absence of write operations (no create/update/delete for campaigns or keywords) could be a gap if management tasks are expected, though it appears intentionally read-only.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.
      6
      99 PyPI
      46
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only analysis of Apple Ads Platform data, allowing AI assistants to query campaign structure, keywords, search terms, and performance reports without modifying anything.
      MIT