aapl-ads-mcp
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: 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,viewInstallsy 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.pemVerifica 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.pemAlmacena 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
Ve a ASA → Account Settings → User Management
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.
Ve a la pestaña API, haz clic en Create Client
Sube
public-key.pemCopia
client_id,team_idykey_idde la pantalla de confirmaciónEncuentra tu
org_iden 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 build4. 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.jsEstablece 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 installEsto configura:
gitleaks protect --staged— bloquea commits que contienen secretosVerificación de lint de Biome en archivos
.tspreparadosVerificació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
.envo*.pem: ambos están en.gitignoreMantén
private-key.pemfuera de la raíz del repositorioEl 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 toolsget_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
Scored across 9 tools
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.
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.
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.
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
Read your Amazon Ads campaigns, results, rules and activity, every marketplace and ad type.
Manage Apple Ads campaigns and reporting in chat.
Read-only Google Ads, Meta Ads and TikTok Ads performance, campaigns and creatives via OAuth.
Google Ads analysis and operations — read performance, manage keywords, bids, and campaigns.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.699 PyPI46MIT
- FlicenseNot gradedqualityDmaintenanceRead-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.-
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceProvides read-only tools for Reddit Ads, listing accounts, campaigns, ad groups, ads, and generating performance reports.1MIT