Apple Ads MCP

Un servidor local-first del Model Context Protocol para la Apple Ads Platform API v1. Proporciona a Codex, Claude y otros clientes MCP herramientas tipadas para la investigación publicitaria en App Store, informes, auditorías y la gestión de campañas protegidas por recibos.

Apple Ads MCP es software de código abierto independiente. No está afiliado a Apple Inc., ni cuenta con su respaldo o patrocinio. Apple Ads y App Store son marcas comerciales de Apple Inc.

Por qué Apple Ads MCP

• Herramientas pensadas para agentes: descubre tus propias apps, investiga palabras clave, consulta informes, audita campañas y prepara cambios de alcance limitado.

• Credenciales locales: la clave privada permanece en tu máquina; los tokens OAuth y los recibos de operación se mantienen en la memoria del proceso.

• Solo lectura por defecto: la investigación y los informes funcionan sin habilitar mutaciones.

• Enrutamiento explícito por cuenta: toda herramienta que requiera una cuenta exige un perfil y un adAccountId.

• Mutaciones seguras: cada escritura requiere una previsualización, un recibo de un solo uso con validez de diez minutos y una revisión del estado actual.

• Salida acotada: contenido MCP estructurado, matrices con límite, paginación, metadatos de límite de velocidad y errores estructurados de Apple.

• Entorno de ejecución portátil: un único binario Go para macOS, Linux y Windows, además de una imagen OCI.

Related MCP server: OpenAI Ads MCP

Estado de la versión

v0.1.0 es la primera versión pública. La suite de pruebas local completa, el detector de carreras, el análisis estático, el escaneo de vulnerabilidades, el escaneo de secretos, la validación de distribución y las pruebas reales de MCP stdio se superan correctamente.

Una aceptación en vivo privada contra una cuenta de Apple Ads controlada por el operador verificó:

• OAuth, detección de cuentas, consulta de organización y de apps propias;

• disponibilidad de tiendas, sugerencias de palabras clave, estadísticas de popularidad e informes acotados;

• previsualización → recibo → aplicación → lectura posterior directa desde la API;

• creación de campañas, grupos de anuncios, palabras clave de segmentación y palabras clave negativas en pausa;

• rechazo por desviación, recibos de un solo uso, restauración de solo lectura y cero gasto publicitario.

Este repositorio no almacena credenciales, exportaciones de cuentas, datos privados de campañas ni recibos en vivo.

Capacidades

Herramientas de lectura

Herramientas de escritura con recibos

• Crea y actualiza campañas, grupos de anuncios, palabras clave de segmentación y palabras clave negativas.

• Utiliza bases de previsualización específicas de la oferta para anuncios y creatividades de App Store; el soporte aún depende de la combinación de ubicación Apple y página de producto.

• Previsualiza pausar/reanudar campañas, pujas de grupos de anuncios y límites de CPA.

• Aplica exactamente una previsualización mediante operations_apply.

• Inspecciona o verifica una operación ambigua con operations_inspect y operations_verify.

No existe ninguna herramienta genérica de solicitudes sin tratar. Apple Maps, la API heredada de gestión de campañas v5, los aumentos automáticos de presupuesto, el borrado destructivo y las operaciones de aplicar/descartar recomendaciones se excluyen deliberadamente.

Modelo de seguridad

Una mutación solo es posible cuando se cumplen todas estas condiciones:

1. El usuario de Apple tiene un rol de escritura API reconocido para la cuenta de anuncios explícita.

2. El servidor se inicia con --allow-writes.

3. El perfil seleccionado tiene allowWrites: true.

4. Una herramienta especializada *_preview devuelve un recibo.

5. operations_apply recibe el mismo recibo no caducado.

6. El recurso Apple actual de la aplicación sigue coincidiendo con el estado leído durante la previsualización.

Los recibos caducan a los diez minutos y son de un solo uso. Las mutaciones nunca se reemprenden si falla el transporte de forma ambigua. El servidor devuelve committed_unverified y exige una comprobación directa del estado antes de cualquier escritura posterior.

Para investigación e informes habituales, ejecuta el servidor sin --allow-writes y mantén todos los perfiles con allowWrites: false.

Instalación

Versiones de GitHub para instalar

Descarga el archivo de tu plataforma desde GitHub Releases. Cada versión incluye sumas SHA-256 y SBOM SPDX.

Ejemplo para el silicio de Apple:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_0.1.0_darwin_arm64.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Fórmula Homebrew

La versión publica una fórmula con suma de verificación fijada como adjunto:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.1.0/apple-ads-mcp.rb
brew install --formula ./apple-ads-mcp.rb

Imagen OCI

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.1.0

La imagen ejecuta serve --stdio por defecto. Monta accounts.json y la clave privada a la que hace referencia en modo de solo lectura. Si la clave es exclusiva del propietario, ejecuta el contenedor con el UID/GID del host correspondiente.

Compilar desde el fuente

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./bin/apple-ads-mcp ./cmd/apple-ads-mcp

Se requiere Go 1.26.6 o superior.

Configuración de la API de Apple Ads

El acceso a la API de publicidad de Apple Ads es distinto del acceso a App Store Connect. Un administrador de cuenta de Apple Ads debe añadir un usuario de API con un rol apropiado. Preferiblemente API Account Read Only hasta que no necesites cambios en las campañas.

Genera un par de claves ES256 localmente:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

Carga únicamente la clave pública en Apple Ads. Mantén la clave privada fuera del repositorio y no la pongas nunca en una conversación con el agente, en una incidencia o en un log.

Cuando Apple registre la clave pública, anota el ID de cliente no secreto y los valores que se muestran en la interfaz de Apple Ads.

Configurar

Crea un perfil de forma interactiva:

apple-ads-mcp config init

La ruta de configuración por defecto es:

~/.config/apple-ads-mcp/accounts.json

Equivalente en JSON:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false
    }
  ]
}

En los sistemas POSIX, ambos archivos deben pertenecer solo al propietario:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

La configuración solo almacena metadatos del perfil y la ruta de la clave privada. Nunca incrusta la clave privada.

Valida la autenticación y descubre las cuentas accesibles:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

Precedencia de configuración:

1. --config

2. APPLE_ADS_MCP_CONFIG

3. ~/.config/apple-ads-mcp/accounts.json

4. Variables de entorno APPLE_ADS_* para un único perfil

Las variables de entorno compatibles son APPLE_ADS_PROFILE, APPLE_ADS_CLIENT_ID, APPLE_ADS_TEAM_ID, APPLE_ADS_KEY_ID, APPLE_ADS_PRIVATE_KEY_PATH, APPLE_ADS_AD_ACCOUNT_ID y APPLE_ADS_ALLOW_WRITES.

Conectar un cliente MCP

Inicia el servidor a través de stdio:

apple-ads-mcp serve --stdio

Configuración MCP genérica para Codex, Claude Desktop u otro cliente stdio:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Claude Code:

claude mcp add apple-ads -- apple-ads-mcp serve --stdio

El archivo de la versión también contiene los metadatos del plugin de Codex y la habilidad apple-ads-operator. La habilidad guía la incorporación, la investigación, los flujos de campañas y la seguridad de las mutaciones sin colocar credenciales en las instrucciones.

Habilitar escrituras en una sesión concreta

Mantén allowWrites: false en el perfil persistente siempre que sea posible. Para una sesión de mantenimiento explícitamente autorizada, activa ambas compuertas temporalmente:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

La ACL de Apple, el profile explícito, el adAccountId explícito, la previsualización, el vínculo del recibo, el tiempo de caducidad y las comprobaciones de desviación siguen aplicándose. Iniciar el servidor con las compuertas de escritura activadas no cambia nada por sí mismo.

Comportamiento conocido de la plataforma

• Apple Ads no tiene entorno de prueba público. Que el CI en vivo deba activarse explícitamente y sea estrictamente de solo lectura.

• Disponibilidad, sugerencias, popularidad, recomendaciones e informes varían según la cuenta, la aplicación, la tienda y el historial de campañas.

• Las cuentas nuevas no devuelvos recomendaciones de CPA objetivo o presupuesto.

• Apple puede devolver errores de validación o errores de servidor específicos de cada endpoint. MCP conserva detalles acotados y seguros para respuestas 4xx y mantiene redactados los errores de servidor reintentables.

• Durante la aceptación en vivo, Apple rechazó un objeto de Anuncio independiente para la fuente de suministro APPSTORE_SEARCH_RESULTS. Los resultados de búsqueda usaban la página de producto predeterminada publicada de la app en su lugar.

• Los nombre de campaña los valida Apple; algunos signos que la interfaz web acepta pueden ser rechazados por la API.

• Los informe de rendimiento quedan vacíos hasta que existen datos de entrega. La atribución de una instalación a una suscripción o prueba pertenece a tu infraestructura de atribución, no a esta API.

• La cobertura completa del runner de conformidad MCP de aguas publicadas sigue pendiente porque el runner actual acepta URL del servidor pero no puede lanzar un proceso hijo de stdio. Este repositorio prueba una sesión real de stdio con el Go SDK oficial.

Desarrollo

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py

Las pruebas en vivo requieren credenciales locales explícitas y nunca realizan mutaciones automáticamente. Consulta [CONTRIBUTING.md](CONTRIBUTING .md), SECURITY.md, el [roadmap](docs /ROADMAP.md) y la matriz de operaciones en formato legible por máquina.

Artefactos de la versión

Cada versión con etiqueta publica:

• Archivos de macOS, Linux y Windows para AMD64 y ARM64 cuando existen soporte;

• checksums.txt con los resúmenes SHA-256;

• facturas de materiales de software SPDX generadas con Syft;

• una fórmula Homebrew con checksum fijado;

• imágenes OCI multienarquitectura para Linux AMD64 y ARM64;

• metadatos de paquetes del Registro MCP.

Licencia

MIT