Everything to run your Meta ads with AI, in one place.

1. Create your account (free) and sign in.
2. Open Meta connection, connect Facebook and pick an ad account.
3. Paste https://ads.viral4all.com/mcp into your AI app and sign in when it asks (steps for every app below).
4. Ask: “How did my ads do this week?” Then set your safety limits on Goals & limits.

Prefer a guided tour? Read How it works.

Pick your app for the exact steps. Most apps just need the URL and a sign-in.

https://ads.viral4all.com/mcp

Pauses run at once (they only stop spend). New campaigns and copies always start paused.

The same tools are in every AI app, the REST API and the CLI. This list comes from the live server. Money is in minor units: 2500 is $25.00.

Every tool is also a plain HTTP endpoint, for scripts, Zapier, Make, n8n and ChatGPT GPT Actions. Make a key on the API keys page and send it as Authorization: Bearer sk_meta_…. Import the OpenAPI schema to get every endpoint at once.

curl -X POST https://ads.viral4all.com/api/public/v1/tools/meta_get_insights \
  -H "Authorization: Bearer sk_meta_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"level":"campaign","datePreset":"last_7d","breakdowns":["age"]}'

GET /api/public/v1/tools lists the tools your key may use, with their input schemas. Changes that spend money answer with an approval link instead of running:

{
  "status": "approval_required",
  "approve_url": "https://ads.viral4all.com/approve/…",
  "confirm_token": "cfm_…",
  "expires_in_seconds": 1800,
  "summary": { "object": { "name": "Spring sale" }, "budget": "daily", "from": "$20.00", "to": "$25.00" }
}

Then call meta_confirm_action with the confirm_token to read the outcome: waiting, done, rejected (with your note), failed or undone.

Key permissions

• ads:read Read ads: List ads with impressions, spend, budget and status.
• ads:create Create ads: Launch new campaigns, ad sets and ads.
• ads:status Pause / resume: Stop and restart ads, single or in bulk.
• ads:creative Update creative: Swap destination links, copy, images and videos.
• ads:budget Set budget: Change daily or lifetime budgets.
• ads:edit Edit ad sets: Change targeting, schedule and bid caps. Each change waits for your approval.
• media:write Upload media: Import an image or video from a URL into Meta.
• sync:write Trigger sync: Force a fresh pull of metrics from Meta.

Sign in once in your browser, then any terminal, script or coding agent can use every tool. Needs Node.js 18 or newer. Add --json for machine output.

npx -y viral4all-ads login              # browser sign-in
npx -y viral4all-ads login --key sk_meta_…  # or an API key
npx -y viral4all-ads ads
npx -y viral4all-ads insights --level campaign --breakdowns age
npx -y viral4all-ads budget 1234567890 2500     # asks for your approval
npx -y viral4all-ads tools                      # everything you can run

Tip: alias v4a="npx -y viral4all-ads". npm blocked? Use npx -y https://ads.viral4all.com/cli/viral4all-ads.tgz instead. Exit codes: 0 ok, 1 tool error, 2 usage error, 3 not signed in. VIRAL4ALL_API_KEY overrides the saved sign-in.

Get told when something happens. Add an https URL on the Webhooks page and pick events. Slack and Discord webhook URLs get a plain message; anything else gets signed JSON.

• approval.requested Your AI asked for a change that waits for your approval.
• approval.approved An AI change was approved and applied.
• approval.rejected An AI change was rejected. Nothing changed.
• approval.failed An approved change didn't go through on Meta.
• change.undone A change was put back the way it was.
• alert.created The daily account check found something, like a spend jump.
• request.blocked An AI request went over one of your limits and was stopped.

{
  "id": "6f1c…",
  "type": "approval.requested",
  "created_at": "2026-10-22T09:30:00.000Z",
  "data": { "approval_id": "…", "action": "budget", "headline": "Spring sale: daily budget $20.00 → $25.00", "approve_url": "https://ads.viral4all.com/approve/…" },
  "text": "Approval needed: Spring sale: daily budget $20.00 → $25.00. Approve or reject: https://ads.viral4all.com/approve/…"
}

Headers: X-Viral4All-Event, X-Viral4All-Delivery and X-Viral4All-Signature: t=…,v1=…, an HMAC-SHA256 of t.body with the secret shown when you added the webhook. Check it before trusting a message:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // older than 5 minutes
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Each event is sent once, with a 5-second timeout; any 2xx answer counts. A webhook that fails 20 times in a row is paused; resume it on the Webhooks page.

The Claude Code plugin adds the connector plus five ready-made workflows: weekly check, what changed, find wasted spend, launch a campaign and safe budget change.

/plugin marketplace add https://ads.viral4all.com/claude/marketplace.json
/plugin install viral4all-ads@viral4all

Also on GitHub: /plugin marketplace add black12-ag/viral4all-ads. The skills work in Claude on the web too: upload them in Settings → Capabilities → Skills (zips are in the Claude steps under Connect your AI).

• Server: https://ads.viral4all.com/mcp (Streamable HTTP). Listed in the official MCP Registry as com.viral4all.ads/mcp.
• Sign-in: OAuth 2.1 with dynamic client registration and PKCE. Discovery at /.well-known/oauth-authorization-server. Scopes: mcp:read (reports only) or mcp:write (everything, with approvals).
• Apps without sign-in: send an API key as Authorization: Bearer sk_meta_….
• AI agents can read /llms.txt to learn how to connect by themselves.

Email [email protected]. Include your account email and the approval link or the time it happened; never send passwords or API keys. More on Support, Privacy and Terms.