Allows preparing, validating, and creating Meta Ads campaigns from a Spanish-language brief, including building campaign specs, validating against the Marketing API, and creating paused campaigns with rollback support.
Supports Click-to-WhatsApp ad creatives by building call-to-action payloads pointing to WhatsApp as the destination.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Servidor MCP para preparar, validar y crear campañas de Meta Ads desde un
brief en castellano. El contrato está congelado en
CAMPAIGN_SPEC.md: ese documento manda, este README solo
cuenta cómo está implementado.
Estado: núcleo completo con la suite de tests de la sección 5 en verde. Nunca se corrió contra la Marketing API real — la sección 6 del spec (log de errores de Meta) sigue vacía justamente por eso.
Regla | Dónde se hace cumplir |
1. Todo se crea en |
|
2. |
|
3. El token no vive en el repo | El perfil guarda |
4. Desarrollo va contra sandbox |
|
5. Presupuestos enteros en unidades menores |
|
6. |
|
Related MCP server: Meta Ads MCP
meta_ads/
errors.py errores con `code` estable + mensaje accionable
enums.py objetivos, compatibilidades, CTAs, mínimos por moneda
profiles.py perfil de cuentas, resolución de cuenta, token, sandbox
brief.py brief en castellano -> hechos (nada que el brief no diga)
spec.py armado del Campaign Spec + provenance + warnings
validate.py validación local (2 severidades) + validate_only contra Meta
payloads.py spec -> payloads de la Marketing API (un solo lugar)
meta_client.py cliente HTTP (solo stdlib, urllib)
create.py creación de los 4 objetos + rollback
server.py adaptador MCP (mcp 1.x y 2.x)
tests/ 80 tests, sin red, stdlibEl núcleo no tiene dependencias: pip install -r requirements.txt solo hace
falta para exponerlo como servidor MCP.
cp profiles.example.json profiles.json # completar ids reales (sandbox)
cp .env.example .env # y exportar SECRET_META_TOKEN_OWN
export META_ADS_PROFILES=$PWD/profiles.json
python3 -m meta_ads.server # stdio
./correr_tests.sh # la suite entera, sin redLos tools se registran con nombre ASCII (preparar_campana, validar_campana,
crear_campana) porque MCP no admite ñ en los identificadores; son los
preparar_campaña / validar_campaña / crear_campaña del documento. Hay un
cuarto tool, listar_cuentas, que no toca Meta: sirve para que el agente pueda
preguntar "¿cuál de estas?" cuando la regla 2 lo obliga a preguntar.
preparar_campana(brief, account_alias?, creatives?) acepta creatives como
lista de dicts escritos por el agente. Si no vienen, el spec sale con
primary_text / headline en null, provenance pending y un warning;
validar y crear los exigen completos. Es la división honesta: el spec
resuelve estructura, el agente escribe texto. Lo mismo con los assets:
image_hash / video_id entran ya resueltos, el spec no sube nada.
Dos campos aditivos y opcionales (un spec sin ellos sigue siendo válido):
preset (raíz): nombre del preset aplicado. Sin esto, las reglas 11-13
de la sección 5 no son verificables. Si falta, validate.py deduce el preset
comparando objective + optimization_goal + destination_type contra los
presets del perfil.
ad_set.destination_type: los presets ya lo definen y la API lo pide.
Y dos valores de provenance que el documento no enumera: pending (copy que
falta escribir) y brief aplicado a account.resolved_by cuando el propio
brief nombra la cuenta.
Esto es lo que hay que mirar primero cuando haya token de sandbox:
validate_only del ad set. Meta exige campaign_id para validar un ad
set, y en preparar la campaña todavía no existe. Hoy se valida la campaña
contra la API y el resto solo localmente; si el spec trae
existing.campaign_id, también se valida el ad set. Ver validar_campana.
Click-to-WhatsApp. payloads.creative_payload arma
call_to_action.value.app_destination = "WHATSAPP" con
link = https://api.whatsapp.com/send. Es la forma más documentada, no está
confirmada contra la cuenta.
Mínimos por moneda (enums.MIN_DIARIO_POR_MONEDA_MINOR): solo el USD
sale de documentación. El resto son valores conservadores. El mínimo
efectivo es max(mínimo de moneda, limits.daily_budget_min_minor), así que
el techo real lo pone el perfil.
Nombres de enum en general: la tabla COMPATIBILIDAD es una foto y
validate_only es el árbitro. Cada Invalid parameter que aparezca se
corrige en enums.py y se anota en la sección 6 del CAMPAIGN_SPEC.md.
Caso | Test |
1. Brief mínimo, una cuenta |
|
2. Brief que sobreescribe defaults |
|
3. Spec válido → |
|
4. |
|
5. Sin cuenta habiendo dos |
|
6. Presupuesto fuera de límites |
|
7. Cualquier |
|
8. Combinación objective/goal/billing inválida |
|
9. |
|
10. Fallo en el POST del ad → rollback |
|
11. |
|
12. |
|
13. |
|
14. |
|
15. |
|
test_invariantes.py cubre las 6 reglas de la sección 1 y el cliente HTTP;
test_server.py, el contrato de los handlers MCP.
Los casos que "deben fallar" se verifican en las dos puertas: preparar los
rechaza al armar el spec y validar/crear los rechazan también si alguien
edita el spec a mano — con la comprobación extra de que la API no se llamó.
This server cannot be deployed
Launch Meta ads with your AI agent. Bulk-create Facebook and Instagram ads, import creatives from public Google Drive links, and launch partnership ads with authorized creators. Reuse proven ad settings, create fresh variations, and review saved builds and previews before launch. Requires an Ads Uploader account with MCP access and a connected Meta account.
AI marketing agent for paid social: Meta ads campaigns, ad creative generation, lead delivery.
Meta Ads MCP: bulk-create Facebook & Instagram ads across accounts from Drive folders, guardrailed.
Run ad campaigns on Meta, Google Ads and LinkedIn from your assistant. Spend waits for your OK.
