Meta Ads Connector

Connect Claude to Meta Ads in one shot, and give it full management of your ad accounts.

Status: built, pending a live run-through. The skill and the package behind it are complete and tested. One full run against a real ad account is still required before release — see Before release.

The problem

Getting Claude connected to Meta Ads is unreliable, and it isn't your fault:

• Meta's official connectors shipped on 29 April 2026 — after Claude's training data. Claude doesn't know they exist, so it improvises.

• Most guides on the web are wrong. They tell you to run npm install -g @meta/ads-cli. That package does not exist. The real one is meta-ads on PyPI.

• Once connected, Claude often tries to connect again, because nothing tells it the job is already done.

Related MCP server: meta-ads-mcp

What this kit does

One skill, meta-ads-connect. It:

• Installs and pins Meta's official Ads CLI, sorting out the Python version for you.

• Mints a system user token that never expires, driving the browser itself — no copying and pasting secrets by hand.

• Sets up your Business Manager and ad account access if you don't already have them.

• Registers Meta's official Ads MCP server alongside, for audiences and Meta's internal benchmark data.

• Checks first. If you're already connected, it says so and stops.

After that, you just talk to Claude about your ads.

What you get access to

Everything: campaigns, ad sets, ads, creatives, image and video upload from your own files, budgets, audiences, and reporting — including Meta-internal signals like opportunity score and industry benchmarks that aren't available through the API at all.

No read-only mode, no artificial limits. Claude will confirm with you before anything that changes spend or sets an ad live.

Requirements

• A Meta ad account (the kit helps you sort out Business Manager if you haven't got that yet)

• Claude Code, in the terminal or inside Claude Desktop

• Python — the kit handles the version for you

Installing

Clone this repo, copy the skill into Claude, and install the package behind it:

git clone https://github.com/lukeselr/meta-ads-connector.git
cd meta-ads-connector

mkdir -p ~/.claude/skills
cp -r skills/meta-ads-connect ~/.claude/skills/

pip install .            # add '.[mint]' for browser-driven token minting

Then just tell Claude: "connect my Meta ads".

Doing it by hand

You never need to run these yourself — Claude does — but each one is safe to re-run:

Where your token lives

~/.meta-ads/.env, readable only by your user account, inside a folder only your user account can open. It is loaded per command — by exec, which is the only thing that puts it into an environment — and never written into your shell profile or your operating system's keychain.

Meta's Ads CLI is installed into ~/.meta-ads/venv rather than onto your PATH, so it cannot collide with any other Python you use, and nothing outside ~/.meta-ads is touched.

To undo everything:

rm -rf ~/.meta-ads              # removes the token and the installed CLI
claude mcp remove meta-ads      # removes the MCP server

To revoke the token at Meta's end — which you should do if you ever think it has leaked — go to Business Settings → System users, select the system user, and remove its token.

Claude is instructed never to print the token, and doctor redacts it from all output, including error messages relayed back from Meta.

Development

uv venv && uv pip install -e '.[dev]'
.venv/bin/python -m pytest      # 198 tests
.venv/bin/python -m mypy        # strict

Tests fake exactly two boundaries — outbound HTTP to Meta, and subprocess execution — and assert on what each subcommand actually does: its exit code, its output, and the state of the filesystem afterwards. No test asserts which internal function was called, so a refactor that keeps behaviour identical cannot break the suite.

Before release

One full live run-through against a real ad account is still required. It is also the moment the outstanding research spike resolves:

1. Does MCP consent actually succeed, and what does the consent screen list?

2. Capture a live tools/list from the MCP server.

3. Does the Claude Code redirect_uri bug still bite in practice?

4. End to end on the CLI: enumerate accounts → create a paused campaign → upload an image creative → verify in Ads Manager → clean up.

5. Confirm the browser selectors in src/meta_ads_connect/minting.py against live Business Settings.

Keeping it accurate

Meta ships changes to these connectors without version bumps and without a changelog. This kit pins what it can and is due a re-check in September 2026. See docs/research/findings-and-decisions.md section 9 for what to check and why.

Licence

MIT