How Do I Connect Claude to the Meta Ads CLI? (Setup + Usage Guide)

Build-in-public post — the setup we use to let Claude read Meta ad data and prescribe the next move. Part of our AI workflows pillar.

Updated October 2026: Meta now has an official option. In April 2026 it released Meta Ads AI Connectors in open beta: a hosted MCP server and an official ads CLI that work with Claude. This post now covers both routes, the official connectors and the read-only wrapper we started with, and when to use each.

The customer pain point

The weekly paid-ads ritual at most brands: export Ads Manager to a spreadsheet, eyeball which creative is fading, manually decide what to test next. It's slow, it's inconsistent week to week, and it's exactly the kind of pattern-recognition work a model does well — if it can actually see the data.

The blocker is access. Claude can't log into Ads Manager. So you either keep copy-pasting screenshots (lossy, slow) or you give it a clean pipe to the Meta Marketing API. This is the pipe.

Table of Contents

• The Official Route: Meta Ads AI Connectors
• The DIY Route: What "Meta Ads CLI" Meant Before
• Setup: Meta API Access
• Setup: The CLI Wrapper
• Connecting Claude (MCP or Pipe)
• Usage Prompts
• What to Watch For

Key Takeaways

The Official Route: Meta Ads AI Connectors

On April 29, 2026, Meta released Meta Ads AI Connectors in open beta. There are two parts, and both talk to the same Marketing API underneath:

• A hosted MCP server. You add it to Claude as a connector and sign in with your Meta business account. Best for asking questions and running reviews in conversation.
• An official ads CLI. For Claude Code and scripted workflows, like the weekly review below.

The connectors cover reporting, campaign management, catalog and dataset operations, and account diagnostics. They are free during the beta. PPC Land has a good write-up of the launch.

The big difference from the setup below: the official connectors can change your account, not just read it. Meta creates new campaigns paused so a person has to switch them on, but edits to budgets and existing campaigns are possible too. Treat that the way you'd treat giving a new hire admin access: useful, and worth a rule that a person approves every change.

For most brands starting today, the official MCP server is the faster way in. The DIY wrapper below is still worth it if you want a strictly read-only analysis pipe, or full control over exactly what data Claude sees.

The DIY Route: What "Meta Ads CLI" Meant Before

Before the official connectors, "Meta Ads CLI" meant a small command-line tool you build that wraps the Meta Marketing API. It exposes a few commands:

• ads:performance --account <id> --since 30d → JSON of every ad's spend, ROAS, CTR, CPM, frequency
• ads:creative --account <id> → creative metadata + thumbnails per ad
• ads:fatigue --account <id> → frequency + declining-CTR flags per ad

Claude calls these, gets clean JSON, and reasons over it. No screenshots, no copy-paste, no lossy context.

Setup: Meta API Access

1. Create a System User — business.facebook.com/settings/system-users → Add → name it branva-ads-readonly.
2. Grant asset access — assign the ad account with read/analyze permission only. Do not grant ad-management write access for the analysis pipe (least privilege — see guardrails).
3. Generate a token — System User → Generate New Token → select your app → scope ads_read only. Set expiry to Never (System User tokens can be permanent).
4. Store the token — environment variable, never in code. META_ADS_TOKEN=..., META_AD_ACCOUNT_ID=act_....

Setup: The CLI Wrapper

A minimal Node/Python script that hits the Marketing API insights endpoint. The core call:

GET https://graph.facebook.com/{API_VERSION}/{ad_account_id}/insights
  ?level=ad
  &fields=ad_name,spend,purchase_roas,ctr,cpm,frequency,impressions,actions
  &date_preset=last_30d
  &access_token={META_ADS_TOKEN}

Use the current Graph API version for {API_VERSION}; Meta retires old versions on a schedule. Wrap that in a command that prints clean JSON to stdout:

node meta-ads.mjs performance --since 30d > /tmp/ads.json

Add a fatigue command that flags ads where frequency > 2.5 AND CTR has declined over the window — that's the creative-fatigue signal Claude will key off.

Connecting Claude (MCP or Pipe)

Option A — MCP server (most integrated). Wrap the CLI commands as MCP tools (ads_performance, ads_creative, ads_fatigue). Claude calls them mid-conversation, reasons, and returns recommendations in one loop. Best for recurring weekly reviews. The account-structure prompts I run on top of it are in How to Run Your Meta Ads Structure With Claude (Prompts Included).

Option B — stdout pipe (fastest to start). Run the CLI, pipe the JSON into a Claude prompt. No MCP infra. Good for proving the workflow before investing in the server.

node meta-ads.mjs performance --since 30d | \
  claude -p "$(cat prompts/weekly-ads-review.txt)"

Start with B, graduate to A once the weekly cadence is set.

Usage Prompts

Weekly creative review:

Here is the last 30 days of Meta ad performance (JSON):

{piped ads.json}

Business context: AOV ${X}, target ROAS {Y}x, monthly budget ${Z}.

Do three things:
1. Rank ads into WINNERS (promote to scaling), HOLDS (keep running)
   and FADING (needs a replacement) based on ROAS vs target AND
   fatigue (frequency > 2.5 with declining CTR). Don't recommend
   switching ads off; Meta moves spend away from weak ads itself.
   Be decisive — name them.
2. For the top 2 winners, identify what they have in common (hook,
   format, angle) — that's the pattern to make more of.
3. Draft 3 new creative test briefs for next week based on the winning
   pattern. Each brief: hook, format, angle, and what it's testing
   vs the current winner.

Be concrete. This goes straight into the creative pipeline.

Spend efficiency check:

From the same JSON: which ad sets are spending the most with the
worst ROAS? Give me the single reallocation that would most improve
blended ROAS this week — move $X from ad set A to ad set B, with the
reasoning. One recommendation, not five.

What to Watch For

• Read-only for analysis. The analysis pipe never needs write access, and if you use Meta's official connectors, keep a person approving every change they make. Claude recommends; a human makes the change in Ads Manager. A write-scoped token connected to an LLM is an unacceptable blast radius. (More on AI failure containment: what AI-run means when the AI screws up.)
• ROAS attribution is Meta's number, not truth. Meta over-attributes to itself. Feed Claude blended/MTA data alongside Meta's if you have it, and prompt it to treat Meta ROAS as relative (compare ads to each other), not absolute. See ecommerce analytics: the 7 KPIs, and for the tracking side, How Do I Connect Meta Ads to Shopify Using Claude?
• Frequency + declining CTR = the fatigue signal. Don't let Claude cut an ad purely on a ROAS dip — early-window noise looks like decline. The fatigue flag (frequency threshold + sustained CTR decline) is the reliable trigger.
• Token cost is trivial here. The JSON for a 30-day account is small (a few thousand tokens). The reasoning call is a few cents. This is a time-saver workflow, not a cost concern — the value is the consistent weekly decision, not compute.
• Keep a human in the creative loop. Claude drafts test briefs; a human (or our creative pipeline) produces and approves the actual creative. We covered why in what an AI marketing agency actually does.

Talk to Branva

We run weekly AI-assisted creative review + the creative pipeline that acts on it as part of transparent monthly marketing. Book a free call — we'll show you the weekly cadence on your own account.

Frequently Asked Questions

Is there an official "Meta Ads CLI"?

Yes, since April 2026. Meta Ads AI Connectors include an official ads CLI and a hosted MCP server, both in open beta. Before that, "Meta Ads CLI" meant a thin wrapper you built over the Marketing API, which is still a good option for a strictly read-only pipe.

Why not just paste Ads Manager screenshots into Claude?

Screenshots are lossy (truncated columns, no exact numbers), not repeatable, and burn vision tokens. A JSON pipe gives Claude exact figures for every ad and makes the weekly review a one-command ritual.

Do I need MCP?

No. Start with the stdout-pipe version (run CLI, pipe JSON into a prompt). MCP makes it a seamless in-conversation loop but it's an optimization, not a requirement.

Should Claude be able to change my ad account?

Only with a person approving each change. For analysis, use a read-only (ads_read) token. Meta's official connectors can make changes, and create new campaigns paused, but nothing should go live or change budget without a human signing off. Never run a write-capable connection in an unattended loop.

What about Google Ads?

Same pattern — wrap the Google Ads API in a CLI, pipe to Claude, use an analogous prompt. The Meta version is documented here because it's where most Shopify brands' spend concentrates.

Related reading

• The AI Workflows pillar — every workflow we run.
• How Do I Use Claude to Analyze My Klaviyo Account? — the email-side equivalent.
• The Complete Guide to Paid Ads for Ecommerce — the strategy this analysis serves.
• Paid Growth pillar — creative testing velocity, CAC math, account structure.