Meta Ads Agents

Campaign performance, creative fatigue and event health.

Quick start · Example output · Tests · Releases · Contributing

A read-only Python toolkit for Facebook and Instagram advertising analysis. Retrieve Marketing API data, inspect campaign and creative performance, and combine specialist findings into reports through the /meta-ads agent workflow.

What you can do

Area	Included capabilities
Performance	Spend, purchases, revenue, ROAS, CPA, CTR and frequency at campaign, ad-set and ad level
Creative	Creative metadata, metrics and fatigue heuristics
Audiences	Age, gender, geography, device and placement breakdowns
Measurement	Pixel/CAPI event health and conversion-funnel checks
Budget	Agent analysis of utilization, pacing and bid-strategy fit
Reports	Markdown, HTML, PDF, CSV tables and period comparisons

The adapters retrieve data; specialist agents interpret it. The complete audit is an agent skill, not a standalone meta_audit.py command. Account mutation is not implemented.

Installation

Requires Python 3.10+, a Meta app and access to the ad account. See docs/SETUP.md for app setup and permissions.

git clone https://github.com/arcbaslow/meta-ads-agents.git
cd meta-ads-agents
python -m venv .venv

Activate with source .venv/bin/activate on macOS/Linux or .venv\Scripts\Activate.ps1 in Windows PowerShell, then:

python -m pip install -e ".[dev]"

Run the adapters from the cloned repository. The project is distributed as an agent toolkit; the source tree includes the scripts, reference material and skill definitions needed for that workflow.

Quick start

Configure credentials using the OAuth browser flow:

python scripts/meta_auth.py --oauth --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
python scripts/meta_auth.py --check
python scripts/meta_auth.py --accounts

The callback listens on localhost:8477. For environments where that flow is unavailable, use the manual configuration path documented in setup. Credentials are stored locally in ~/.claude/meta-ads-credentials.json; never commit that file.

Replace the example account ID with one returned by --accounts:

python scripts/meta_insights.py --account act_123456789 --days 30
python scripts/meta_creatives.py --account act_123456789 --with-metrics
python scripts/meta_events.py --account act_123456789 --health-check

Both 123456789 and act_123456789 are accepted and normalized to act_123456789. Data adapters print JSON to stdout.

Example output

This screenshot shows the actual Markdown report rendered for documentation, with synthetic campaign data. Reproduce it without a Meta account:

python scripts/meta_report.py --input examples/demo/account.json --format md --output report.md
python scripts/meta_report.py --input examples/demo/account.json --format html --output report.html

Read the generated report or inspect the report input. The report input is an assembled report object, not the raw response from meta_insights.py.

Agent workflow

With the repository's plugin and skills loaded, the router provides:

/meta-ads audit act_123456789
/meta-ads performance act_123456789
/meta-ads creative act_123456789
/meta-ads audience act_123456789
/meta-ads events act_123456789
/meta-ads budget act_123456789

The audit skill distributes work across the specialists in agents/, then combines their findings. Other agent runtimes can follow AGENTS.md and run the underlying adapters directly.

Reports and comparisons

python scripts/meta_insights.py --account act_123456789 --level adset --breakdown age --days 30
python scripts/meta_report.py --input examples/demo/account.json --format pdf --output report.pdf
python scripts/meta_report.py --input examples/demo/account.json --format csv --output csv-output
python scripts/meta_report.py --input current.json --compare previous.json --format md --output comparison.md

Campaign queries typically use 30 days; event checks use 7. Inspect the adapter's --help for overrides. Benchmark reference files in skills/meta-ads/references/ support interpretation; they are bundled reference material, not continuously updated market data.

Caching and API behavior

Responses use a 15-minute JSON cache under the OS temporary directory, in claude-meta-ads/. Pass --no-cache to refresh a supported adapter query. Retryable rate-limit errors and transient connections use exponential backoff. Field availability still depends on the account, permissions and API version. Fatigue and event-health signals are heuristics to investigate, not proof of a cause.

Tests

python -m ruff check scripts/
python -m pytest scripts/ -q

The fixture-based suite requires no Meta account and covers auth and OAuth state validation, cache behavior, campaign and audience queries, creative scoring, event health, report formats, agent-command parsing and version consistency. CI runs Python 3.10–3.13. See the release verification.

Repository map

Path	Purpose
scripts/	Marketing API adapters, reports and tests
agents/	Performance, creative, audience, events and other specialists
skills/	/meta-ads commands and analysis reference material
examples/demo/	Synthetic report input and generated Markdown
docs/	App setup, releases and verification

Releases

v1.0.2 — see the release notes for this release and the changelog for project history.

GitHub Releases include downloadable artifacts and checksums. Package-registry publication is a separate, opt-in workflow; a GitHub release does not imply that the same version is available on PyPI or npm. Maintainers can follow the release guide.

Contributing

Read CONTRIBUTING.md, run the checks above, and include a minimal reproduction for bugs. Report vulnerabilities through SECURITY.md.

Related tools

Project	Use it for
Google Ads Agents	Paid media audits, tracking checks and reviewed changes.
Google Analytics Agent	GA4 data quality, funnels and property management.
Search Console Agent	Search performance, indexing and page experience.
GTM Diff	Review the changes in your Google Tag Manager exports.
Figma Taxonomy Gen	Turn interactive designs into a reviewable tracking plan.

Maintained by Good Labs — measurement implementation, tracking plans and analytics audits.

License

MIT © Dilshat Rakhimov. This is an independent project; it is not an official product of the platform vendors.