Nexus for Meta — connect Facebook Ads, Pages & Instagram to Claude

Ask Claude about your Meta marketing in plain English and get the real numbers
back. "What's my cost per lead this month?" "Which ad is my best?" "How
many leads came in this week?" Claude pulls live data straight from the Meta
Marketing API and answers.

No dashboards. No CSV exports. No MCP server to install or keep running. Just
your own Meta account, one access token, and curl.

📖 Full documentation and FAQ →

What you can ask

• "How did my ads perform last month? Spend, leads, cost per lead."
• "Break performance down by campaign, then by ad."
• "Which ad is my best? Give me the Instagram link."
• "How many leads came in this week, and from which form?"
• "How are my Page and Instagram accounts growing?"
• "Draft a new campaign for X." Claude builds it paused and confirms with
  you before anything goes live.

It reads by default. It only creates, edits or pauses things when you ask, and it
confirms the exact change and the dollar amounts first.

See examples/ for real transcripts of the kit answering real
questions.

How to connect Facebook Ads to Claude

You'll run this in Claude Code, either the
CLI or the Claude desktop app. Paste this to Claude:

Clone https://github.com/redwoodmeridian/nexus-for-meta, open it, read its
README and follow the setup to connect my Meta account. I already have my
system-user token ready to paste.

Claude clones the repo, sets up your .env, and asks for your token. Paste the
token right into the chat. Claude saves it and confirms the connection. You're
live.

Don't have a token yet? Claude will walk you through SETUP.md,
which covers two ways to create one.

git clone https://github.com/redwoodmeridian/nexus-for-meta
cd nexus-for-meta
cp .env.example .env      # paste your token after META_TOKEN=
./scripts/verify          # confirms what the token can reach

What you need

• The Claude Code CLI or the Claude desktop app.
• A Meta system-user access token for your business. Takes a few minutes to
  create and it never expires. See SETUP.md.

That's it. curl is already on your Mac, Windows and Linux machine.

What's inside

Your token lives only in .env, which is git-ignored and never leaves your
machine.

Using the script directly

./scripts/meta me/adaccounts "fields=account_id,name"
./scripts/meta act_123/insights "date_preset=last_30d&level=campaign&fields=campaign_name,spend,actions"
./scripts/meta --page PAGE_ID PAGE_ID/leadgen_forms "fields=name,leads_count"
./scripts/meta --post CAMPAIGN_ID "status=PAUSED"

Frequently asked questions

Is there a Meta Ads MCP server for Claude?

Nexus for Meta deliberately does not use MCP. There is no server to install, run
or keep alive. Claude calls the Meta Graph API directly with curl using your
access token. Nothing to maintain, no extra process, and no third party sitting
between your ad data and Claude.

Do I need to build my own Meta app to use the Marketing API?

You can, but you don't have to. SETUP.md covers two paths: request
access to an existing shared app, or create your own Business-type app. Your own
app stays in Development mode and needs no App Review, because you're only ever
accessing accounts you own.

Can Claude create or pause my Facebook campaigns?

Yes, but only when you explicitly ask for that specific change. The kit defaults
to read-only. Every write is described in plain language with the exact dollar
amounts before it runs, and new campaigns are always created paused so nothing
can start spending by accident.

Is it safe to give Claude my Meta access token?

The token is stored only in a local .env file that is git-ignored and never
leaves your machine. Requests go straight from your computer to
graph.facebook.com, with nothing routed through a third-party server. The token
does carry ads_management, so it can spend money, which is why the kit defaults
to read-only and confirms every write.

What Meta permissions does the token need?

ads_read, ads_management, pages_show_list, pages_read_engagement,
pages_manage_metadata, pages_manage_posts, instagram_basic,
instagram_manage_insights, leads_retrieval and business_management. Grant
only what you need. ads_read alone is enough for reporting.

Why do I get error 190 on Page posts or lead forms?

Page-level endpoints need a Page access token, not the user token. Pass --page
and the script fetches the right one for you:

./scripts/meta --page PAGE_ID PAGE_ID/leadgen_forms "fields=name,leads_count"

Ad-account reads don't need this.

Which Meta Graph API version does it use?

v25.0, the current version. Set META_API_VERSION in .env to pin a different
one without touching any code.

Something's broken. How do I debug it?

./scripts/doctor

It checks your local setup, the token's type, expiry and permissions, and which
ad accounts, Pages and Instagram accounts it can actually reach. Then it names
the specific fix instead of printing a raw error code.

What does Nexus for Meta cost?

Nothing. It's open source under the MIT License. You need a Claude subscription
and your own Meta ad account. There are no other costs and no hosted service.

Who built this

Nexus for Meta was built by Irfad Imtiaz,
Director of Technology at My Legal Academy,
which publishes and maintains it.

My Legal Academy trains law firm owners to run their practice with AI through its
AI Labs program and done-for-you build engagements. This kit came out of getting
real firms off the Ads Manager and onto a conversation with their own data.

Find Irfad on LinkedIn and
GitHub.

If you cite or write about this project, please credit Irfad Imtiaz as the
author and My Legal Academy as the publisher. There's a
CITATION.cff if you need a machine-readable version.

More open-source kits

License

MIT © My Legal Academy (Redwood
Meridian). Free to use, adapt and build on.