Apple Ads MCP Server

La API de Apple Ads Platform, como servidor MCP. 99 operaciones en todos los recursos documentados, expuestas a Claude Code, Claude Desktop, Cursor y cualquier otro cliente del Model Context Protocol a través de 4 herramientas eficientes en tokens.

apple-ads-mcp es un servidor Model Context Protocol (MCP) de código abierto para la API de Apple Ads Platform — la API detrás de Apple Search Ads y los anuncios de marca de Apple Maps. Instálalo una vez y tu agente de IA puede leer y escribir campañas, grupos de anuncios, palabras clave, creatividades, presupuestos, informes y todo lo demás que Apple expone para tus cuentas publicitarias.

El catálogo se genera a partir de openapi/apple-ads.openapi.json, reconstruido desde el cliente Node oficial de Apple (apple/apple-ads-platform-api-node, etiqueta de especificación 109) y contrastado endpoint por endpoint con la documentación publicada por Apple.

En este repositorio no hay credenciales. Tú proporcionas tus propias credenciales de la API de Apple Ads en tiempo de ejecución mediante variables de entorno. Nada se empaqueta, se registra ni se transmite a ningún lugar salvo a Apple.

Tabla de contenidos

• Por qué 4 herramientas en lugar de 99

• Qué puedes hacer con él

• Requisitos

• Cómo obtener tus credenciales

• Instalación y configuración

• Las cuatro herramientas

• Un ejemplo práctico

• Alcance de la cuenta publicitaria

• Consulta, paginación y ordenación

• Informes

• Subida de recursos creativos

• Errores y límites de frecuencia

• Prueba en seco

• Variables de entorno

• Cómo se genera el catálogo

• Vía de escape: cada operación como herramienta propia

• Seguridad

• Contribuciones

• Licencia

Por qué 4 herramientas en lugar de 99

Registrar las 99 operaciones de Apple Ads como herramientas MCP individuales significa volcar 99 esquemas JSON completos en la ventana de contexto del modelo antes de que haga ningún trabajo real. La mayor parte de ese presupuesto se desperdicia en operaciones que el agente nunca llama en una conversación determinada.

Este servidor mantiene el catálogo completo interno y expone una pequeña superficie estable sobre él:

ads_search  →  find operations           (names, methods, paths, tags — no schemas)
ads_schema  →  describe one operation    (full input JSON Schema + call hint)
ads_call    →  execute one operation     (real request, or _dryRun)
ads_tags    →  list resource tags        (with operation counts, to narrow search)

El agente paga exactamente por el esquema que está a punto de usar, y nada más. Un flujo típico de búsqueda → esquema → llamada cuesta unos pocos miles de tokens en lugar de las decenas de miles que costaría cargar todos los esquemas por adelantado — y no pierde cobertura, porque el catálogo completo de 99 operaciones sigue siendo accesible a través de ads_search y ads_call.

Related MCP server: mlg-meta-mcp

Qué puedes hacer con él

Las 99 operaciones en 28 etiquetas de recursos. Ejecuta ads_tags en cualquier momento para obtener la lista exacta y actualizada con recuentos.

• Campañas — crear, leer, actualizar, eliminar, consultar con filtro/orden/paginación (Campaigns)

• Grupos de anuncios — crear, leer, actualizar, eliminar, consultar (AdGroups)

• Palabras clave y palabras clave negativas — crear, leer, actualizar, eliminar, consultar, además de creación/actualización masiva para ambas (Keywords, NegativeKeywords)

• Anuncios — crear, leer, actualizar, eliminar, consultar (Ads)

• Creatividades — crear, leer, actualizar, eliminar, consultar (Creatives)

• Recursos — subir, leer, eliminar, consultar — las imágenes y vídeos utilizados en creatividades y en los anuncios de marca de Apple Maps (Assets)

• Páginas de producto — leer páginas de producto personalizadas y sus detalles de configuración regional, consultar (ProductPages)

• Presupuestos compartidos — crear, leer, actualizar, eliminar, consultar — presupuestos compartidos entre varias campañas (SharedBudgets)

• Geografía y ubicaciones — buscar y consultar ubicaciones segmentables, gestionar grupos de ubicaciones (Locations, LocationGroups, Search)

• Anuncios de marca de Apple Maps — marcas comerciales y categorías comerciales para campañas basadas en Maps (Brands, Categories)

• Informes — informes de rendimiento de apps y marcas comerciales por campaña, grupo de anuncios, anuncio, palabra clave y término de búsqueda (Reports)

• Información — cuota de impresiones y popularidad de términos de búsqueda (Insights)

• Recomendaciones — recomendaciones de presupuesto diario y CPA objetivo: consultar, aplicar, descartar (Recommendations)

• Sugerencias — sugerencias de palabras clave, frases, categorías y CPA objetivo para desarrollar campañas (Suggestions)

• Historial de cambios — resúmenes de auditoría y detalles de cambios para una cuenta publicitaria (ChangeHistory)

• Gestión de cuentas y accesos — cuentas publicitarias, información de la organización, ACL de usuarios, identidad del llamante autenticado, recursos de anunciante (AdAccounts, Orgs, Acls, Me, AdvertiserResources)

• Búsqueda de apps, elegibilidad y metadatos — buscar en el catálogo de App Store, comprobar la elegibilidad para anuncios en App Store, consultar los detalles de configuración regional de la app, idiomas admitidos y motivos de rechazo de apps y marcas (Apps, Search, Eligibilities, Metadata, RejectionReasons)

Requisitos

• Bun 1.1 o superior

• Una cuenta de Apple Ads con acceso a la API — un ID de cliente, ID de equipo, ID de clave y una clave privada, desde la interfaz de Apple Ads

• Un cliente MCP que hable stdio: Claude Code, Claude Desktop, Cursor o tu propio agente

Cómo obtener tus credenciales

1. Inicia sesión en ads.apple.com.

2. Genera una clave privada EC localmente (Apple nunca ve la clave privada en sí):

   openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem
   openssl ec -in private-key.pem -pubout -out public-key.pem

3. Ve a Configuración de la cuenta → API, pega el contenido de public-key.pem (incluyendo las líneas BEGIN/END) en el campo Public Key y guarda.

4. Después de guardar, la página muestra tu bloque de credenciales: un Client ID, un Team ID y un Key ID. Copia los tres.

5. Mantén private-key.pem fuera de tu repositorio, por ejemplo en ~/.apple-ads/private-key.pem, y aplícale chmod 600.

Este servidor se encarga del resto: firma el JWT de secreto de cliente ES256, lo intercambia por un token de acceso y guarda el token en memoria. Consulta Alcance de la cuenta publicitaria para saber cómo encontrar tu ID de cuenta publicitaria una vez que tengas las credenciales.

Instalación y configuración

git clone https://github.com/imfaisii/apple-ads-mcp.git
cd apple-ads-mcp
bun install
bun run smoke     # offline catalog check + server boot — no credentials needed

Copia .env.example a .env y rellena tus valores, o pásalos directamente en la configuración de tu cliente MCP. Cualquier cliente que lance un servidor MCP stdio funciona de la misma manera: mcp.example.json en este repositorio es una plantilla lista para copiar:

{
  "mcpServers": {
    "apple-ads": {
      "command": "bun",
      "args": [
        "run",
        "/ABS/PATH/to/apple-ads-mcp/src/index.ts"
      ],
      "env": {
        "APPLE_ADS_CLIENT_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "APPLE_ADS_TEAM_ID": "SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "APPLE_ADS_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "APPLE_ADS_PRIVATE_KEY_PATH": "/ABS/PATH/to/private-key.pem",
        "APPLE_ADS_AD_ACCOUNT_ID": "1234567"
      }
    }
  }
}

Claude Code — regístralo globalmente:

claude mcp add apple-ads \
  -s user \
  -t stdio \
  -e APPLE_ADS_CLIENT_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e APPLE_ADS_TEAM_ID=SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e APPLE_ADS_KEY_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e APPLE_ADS_PRIVATE_KEY_PATH=$HOME/.apple-ads/private-key.pem \
  -e APPLE_ADS_AD_ACCOUNT_ID=1234567 \
  -- bun run /ABS/PATH/to/apple-ads-mcp/src/index.ts

claude mcp get apple-ads

Inicia una nueva sesión. Las herramientas aparecen como mcp__apple-ads__ads_search, …ads_schema, …ads_call y …ads_tags.

Claude Desktop — añade el mismo bloque mcpServers que se muestra arriba a claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Reinicia Claude Desktop después de editarlo.

Cursor — ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto), el mismo bloque mcpServers.

Tu propio agente — ejecuta bun run src/index.ts y habla MCP a través de stdio. Parecerá que se queda colgado en una terminal en crudo; eso es un servidor stdio esperando a un cliente, y es correcto.

Las cuatro herramientas

ads_search — encuentra la operación correcta

Búsqueda de texto libre sobre operationId, nombre, ruta, etiquetas, método y descripción. Devuelve resultados ordenados sin los esquemas JSON.

* Se requiere al menos uno de query, tag o method.

{ "query": "create campaign", "method": "POST", "limit": 5 }

ads_schema — describe una operación

Devuelve el esquema JSON completo de entrada de la operación, sus listas de parámetros de ruta/consulta/cabecera y un callHint que muestra cómo invocarla.

{ "operation": "campaigns_create" }

ads_call — ejecuta la operación

Los campos de ruta y consulta, adAccountId y _dryRun funcionan tanto anidados dentro de args como como claves de nivel superior junto a operation.

// query campaigns
{
  "operation": "campaigns_query",
  "args": {
    "body": {
      "filters": [{ "field": "status", "operator": "EQUALS", "value": "ENABLED" }],
      "pagination": { "pageSize": 10, "fetchTotalCount": true }
    }
  }
}

// create a campaign
{
  "operation": "campaigns_create",
  "args": {
    "body": {
      "name": "Away Finder — Brand",
      "billingEvent": "TAPS",
      "startTime": "2026-09-01T00:00:00Z",
      "promotedObjectType": "APPSTORE_APP",
      "promotedObjectId": "1234567890",
      "status": "ENABLED",
      "dailyBudget": { "value": { "amount": "50.00", "currency": "USD" } }
    }
  }
}

ads_tags — oriéntate dentro de la API

{}

Un ejemplo práctico

Un flujo completo desde cero contexto hasta una llamada real: descubre la cuenta publicitaria, encuentra la operación, lee su esquema y luego ejecútala.

1. ads_call     { operation: "acls_list" }
   → { result: { acls: [ { adAccount: { id: 123456789, name: "Away Finder" }, roles: ["Admin"] } ] } }
   Use adAccount.id as the ad account for every scoped call below.

2. ads_search   { query: "list campaigns" }
   → hits: [ { name: "campaigns_query", operationId: "campaignsQueryPost", method: "POST", path: "/campaigns/query", tags: ["Campaigns"] }, ... ]

3. ads_schema   { operation: "campaigns_query" }
   → full inputSchema (adAccountId, body.filters, body.sorting, body.pagination) + callHint

4. ads_call     {
     operation: "campaigns_query",
     args: {
       adAccountId: "123456789",
       body: {
         filters: [{ field: "status", operator: "EQUALS", value: "ENABLED" }],
         sorting: [{ field: "name", order: "ASC" }],
         pagination: { pageSize: 10, fetchTotalCount: true }
       }
     }
   }
   → { status: 200, body: { result: [ { id: 542370549, name: "Away Finder — Brand", status: "ENABLED", ... } ], pagination: { offset: 0, pageSize: 10, totalCount: 1 } } }

Para crear algo en lugar de listarlo, ejecuta la misma forma como prueba en seco primero (consulta Prueba en seco), comprueba la solicitud resuelta contra ads_schema y luego haz la llamada real.

Alcance de la cuenta publicitaria

La mayoría de las llamadas de Apple Ads están limitadas a una cuenta publicitaria. El servidor envía esto como cabecera X-Ap-Context:

X-Ap-Context: adAccountId=123456789;

No construyes esta cabecera tú mismo. O bien:

• establece APPLE_ADS_AD_ACCOUNT_ID una vez en tu entorno, para que todas las llamadas con ámbito lo usen por defecto, o

• pasa adAccountId en cada llamada dentro de args (o como campo de nivel superior junto a operation), lo que anula el valor por defecto solo para esa llamada.

Un puñado de operaciones no necesitan una cuenta publicitaria y funcionan solo con tu token de acceso: me_list (GET /me) y acls_list (GET /acls). Llama primero a acls_list — devuelve todas las cuentas publicitarias a las que pueden acceder tus credenciales, además de tu rol en cada una, para que sepas qué valores de adAccountId son válidos antes de acotar cualquier otra llamada a una de ellas.

Consulta, paginación y ordenación

La mayoría de los endpoints de tipo lista siguen la misma forma: POST /<resource>/query con un cuerpo selector de filters, sorting y pagination. Este es el mismo patrón tanto si consultas campañas, grupos de anuncios, palabras clave, creatividades o un informe.

// POST /campaigns/query
{
  "filters": [
    { "field": "status", "operator": "EQUALS", "value": "ENABLED" }
  ],
  "sorting": [
    { "field": "name", "order": "ASC" }
  ],
  "pagination": {
    "offset": 0,
    "pageSize": 10,
    "fetchTotalCount": true
  }
}

Filters (field, operator, value, ignoreCase opcional) admiten un amplio conjunto de operadores: EQUALS, NOT_EQUALS, IN, NOT_IN, CONTAINS_ANY, CONTAINS_ALL, NOT_CONTAINS_ANY, NOT_CONTAINS_ALL, STARTS_WITH, ENDS_WITH, LIKE, NOT_LIKE, BETWEEN, GREATER_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN, LESS_THAN_OR_EQUAL_TO, IS_NULL, IS_NOT_NULL. No todos los campos de cada entidad admiten todos los operadores: consulta la lista de campos en ads_schema para la operación que estés llamando.

Sorting acepta field y order (ASC o DESC). Si se omite, los resultados se ordenan por id ascendente.

Pagination acepta offset y pageSize, con fetchTotalCount (por defecto false) para devolver también el recuento total de coincidencias. Los endpoints de informes limitan pageSize a 5000 y usan 100 por defecto cuando se omite; los demás endpoints /query no documentan un límite fijo: empieza con un pageSize moderado y pagina con offset.

Las palabras clave y las palabras clave negativas también tienen endpoints masivos (keywords_bulkCreate, keywords_bulkUpdate, negativeKeywords_bulkCreate, negativeKeywords_bulkUpdate) que aceptan un array de items, cada uno con un correlationId proporcionado por el cliente y un payload data, además de un indicador allowPartialSuccess.

Informes

La etiqueta Reports cubre 10 operaciones: informes de rendimiento a nivel de app y de marca empresarial por campaña, grupo de anuncios, anuncio, palabra clave y término de búsqueda (reports_appsCampaignsQuery, reports_appsAdgroupsQuery, reports_appsAdsQuery, reports_appsKeywordsQuery, reports_appsSearchtermsQuery, y los equivalentes reports_businessBrandsCampaignsQuery / reports_businessBrandsAdgroupsQuery / reports_businessBrandsAdsQuery / reports_businessBrandsKeywordsQuery / reports_businessBrandsSearchtermsQuery para anuncios de marca de Apple Maps).

Cada operación de informe es una llamada POST /reports/.../query que acepta el mismo cuerpo selector de filters / sorting / pagination descrito anteriormente, limitado a una cuenta publicitaria:

{
  "operation": "reports_appsCampaignsQuery",
  "args": {
    "adAccountId": "123456789",
    "body": {
      "pagination": { "pageSize": 100 }
    }
  }
}

Ejecuta ads_schema { operation: "reports_appsCampaignsQuery" } primero para ver los campos exactos filtrables/agrupables de ese informe antes de llamarlo: difieren según el tipo de informe.

Subida de activos creativos

assets_upload es la única operación que envía multipart/form-data en lugar de JSON. Un cliente MCP solo puede enviar JSON, por lo que la parte del archivo se describe como un objeto y el servidor la convierte en una subida multipart real:

{
  "operation": "assets_upload",
  "args": {
    "adAccountId": "123456789",
    "body": {
      "file": { "path": "/Users/you/creative/hero.png", "contentType": "image/png" },
      "promotedObjectId": "987654",
      "promotedObjectType": "BUSINESS_BRAND"
    }
  }
}

Usa { "path": "/abs/path" } para leer un archivo de la máquina que ejecuta el servidor, o { "base64": "...", "filename": "hero.png", "contentType": "image/png" } cuando los bytes ya están disponibles. Apple acepta PNG, JPG y HEIC aquí.

Errores y límites de frecuencia

• El cuerpo de respuesta de Apple se transmite intacto. En un 4xx/5xx, el agente ve el error.code, error.message y error.details propios de Apple, para que pueda leer exactamente qué se rechazó y autocorregirse.

• En 401, este servidor renueva el token de acceso una vez y reintenta automáticamente: no deberías ver errores de token caducado llegar al agente.

• En 429, la respuesta incluye un hint más las cabeceras de límite de frecuencia que Apple envió (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y Retry-After cuando está presente). El servidor no reintenta en tu nombre: retrocede usando esas cabeceras, prefiriendo Retry-After cuando esté presente. La documentación de Apple no publica un límite numérico fijo, así que no lo fijes en código; lee las cabeceras en cada respuesta.

• Una solicitud masiva (keywords_bulkCreate, etc.) cuenta como una sola llamada contra el límite de frecuencia sin importar cuántos elementos lleve: agrupa los cambios en solicitudes masivas cuando operes a escala.

• Las respuestas de más de ~120 000 caracteres se truncan con una sugerencia para acotar la solicitud. Para endpoints de listas/informes, baja pageSize o añade filters más específicos en lugar de traerlo todo de una vez.

Ejecución en seco

Cada ads_call acepta _dryRun: true. Resuelve la solicitud (método, ruta, parámetros de ruta, query, cabeceras, cuerpo y el contexto de la cuenta publicitaria) sin enviar nada a Apple:

{
  "operation": "campaigns_update",
  "_dryRun": true,
  "args": {
    "id": "542370549",
    "adAccountId": "123456789",
    "body": { "status": "PAUSED" }
  }
}

{
  "dryRun": true,
  "operationId": "campaignsIdPut",
  "method": "PUT",
  "path": "/campaigns/{id}",
  "pathParams": { "id": "542370549" },
  "query": {},
  "headers": {},
  "body": { "status": "PAUSED" },
  "adAccountId": "123456789",
  "xApContext": "adAccountId=123456789;"
}

Úsalo para comprobar una solicitud de escritura contra ads_schema antes de que toque una cuenta publicitaria real.

Variables de entorno

* Proporciona exactamente uno de APPLE_ADS_PRIVATE_KEY_PATH o APPLE_ADS_PRIVATE_KEY.

Copia .env.example a .env para shells locales. .env*, *.p8 y *.pem ya están en .gitignore.

Cómo se genera el catálogo

openapi/apple-ads.openapi.json   →   bun run generate   →   generated/tools.json
                                                              generated/manifest.json

openapi/apple-ads.openapi.json es la fuente de verdad incorporada: reconstruido a partir del cliente Node oficial de Apple (apple/apple-ads-platform-api-node, etiqueta de especificación 109) y verificado endpoint por endpoint contra la documentación publicada de Apple. scripts/generate-tools.ts lo lee y emite una entrada de catálogo por ruta+método (99 operaciones, 80 rutas, 28 etiquetas) en generated/tools.json, además de recuentos y procedencia en generated/manifest.json.

Las descripciones de las herramientas se enriquecen con la documentación propia de Apple. generated/docs.json asigna cada METHOD /path al título, resumen y URL de su página en developer.apple.com, de modo que ads_search y ads_schema devuelven el texto propio de Apple y un enlace que puedes abrir.

bun run generate   # rebuild the catalog from openapi/apple-ads.openapi.json
bun run docs       # refresh generated/docs.json from developer.apple.com
bun run smoke      # regenerate, validate the catalog, boot the server

La cobertura está verificada, no asumida. Apple publica 99 páginas de endpoints; este catálogo tiene 99 operaciones, y cada una coincide 1:1 por método y forma de ruta. La comparación completa endpoint por endpoint está en docs/endpoint-coverage.md.

generated/ es salida de compilación. Nunca lo edites a mano: cambia la especificación o el generador y luego regenera. CI falla si el catálogo confirmado no coincide con una generación nueva.

Vía de escape: cada operación como herramienta propia

export APPLE_ADS_EXPOSE_ALL_TOOLS=1   # also register all 99 operations as individual MCP tools

Déjalo sin definir en uso normal: existe para depurar el catálogo generado, no para el uso diario del agente, y pone el esquema completo de cada operación de nuevo en contexto.

Seguridad

• No se almacena ningún secreto en este repositorio. Las credenciales provienen únicamente de variables de entorno.

• .gitignore bloquea *.p8, *.pem, PrivateKey_*.p8 y .env*.

• El secreto de cliente es un JWT ES256 de corta duración por política que firmas localmente con tu clave privada (válido hasta 180 días, el máximo propio de Apple); Apple nunca recibe la clave privada en sí. El token de acceso resultante se almacena en caché solo en memoria y se renueva con un margen de 60 segundos antes del expires_in que devuelve Apple (actualmente 3600 segundos), más un reintento único en un 401.

• Los resultados de las herramientas nunca devuelven credenciales al modelo.

• Los únicos destinos de red son APPLE_ADS_BASE_URL (por defecto el host de la API de Apple) y APPLE_ADS_AUTH_BASE_URL (por defecto el host OAuth de Apple).

• Si alguna vez confirmas una clave privada por accidente, rótala inmediatamente en la interfaz de Apple Ads.

Consulta SECURITY.md para informar de una vulnerabilidad.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Consulta CONTRIBUTING.md. Dos reglas importan más: generated/ se regenera en lugar de editarse a mano, y ninguna credencial debe aparecer jamás en una solicitud de extracción.

Licencia

MIT © imfaisii

No afiliado ni respaldado por Apple Inc.