Skip to content
← Setup kits and setup guides

Setup guide · last checked October 17, 2026

An analysis system that reviews competitors' ads and ranks your own leads

Two separate paths: turn competitors' live ads into a sourced observation report, or rank your own (or permission-based) lead list against clear criteria and create follow-up tasks. Claude Ads' audit command only looks at your own account's export.

Compiled from the official documentation. The basis for each step is listed under it.

What you get

On the competitor path, a comparison report with every source and date written down; on the lead path, a lead list scored against your criteria and follow-up tasks assigned to an owner.

How it runs

You start it. You start every run yourself; the system does not repeat on its own, makes no changes to any account and sends no messages to anyone. On the lead path, you upload your list to the services you use (Claude, and Clay if you choose).

Where it runs

Windows · macOS · Linux · Browser

What the cost depends on

Subscription · No cost · API usage · Setup service

Who it is for

  • Business owners and agencies who want to see, on a regular basis, which messages and formats their competitors use
  • Sales and marketing teams who want to rank their permission-based lead list by criteria and hand follow-up to an owner

Who it is not for

  • People who want to build a lead list by scraping follower lists or email addresses
  • People who want to send bulk direct messages or automated WhatsApp sequences
  • People who want the ad account to spend money or run campaigns on its own
  • People who treat a competitor's ad simply being visible as proof that the ad is profitable

How the system fits together

Competitor path: Meta Ad Library observations → a sourced report in Claude; if you have your own ad account, its export is audited separately with Claude Ads (the /ads audit command looks at your own export, not at competitors; you have Claude write the competitor report from your observation table). Lead path: permission-based list → ranking by criteria → follow-up task; Clay is optional.

  • Claude Code required

    The workspace where you have the report and the lead ranking written from the observation table

    Tool guide

  • Claude Ads optional

    A plugin that audits your own ad account's export (/ads audit, read-only). The plugin also has an /ads competitor skill that researches competitors from transparency sources; this guide does not use it

    Alternative: If you don't have an ad account, don't install this tool; the report relies only on your observations

    Tool guide

  • Meta Ad Library required

    Observing competitors' live ads

    Alternative: Atria, if you want a tool that offers search, tracking and AI insights instead of the Library

    About the tool

  • Atria optional

    An additional competitor ad search tool; its coverage is not the same as the Meta Ad Library (it is Atria's own library)

    Alternative: If the Meta Ad Library interface isn't enough and you like Atria after trying the free account

    Tool guide

  • Clay optional

    Optional: for organizing a large list; you can give a small list to Claude directly as a CSV

    Alternative: If you can already organize your data in a CRM, Clay isn't required

    Tool guide

Connections between tools

  • Meta Ad Library Observation table (CSV) · Manual transfer · You enter the source, date, message and format of each ad you see into the table yourself
  • Atria Claude · Connected via MCP · A custom connector in Claude (claude.ai) or claude mcp add in Claude Code; URL https://api.tryatria.com/mcp, sign in with your Atria account · permission: Searching the Atria library and reading the workspace; asks for approval before changes and deletions
  • Your own ad account Claude Ads · Via a file · A CSV or JSON export file you download from the account
  • Lead list Clay · Via a file · The CSV file is imported and its columns are mapped
  • Ranked list Follow-up task · Manual transfer · You assign the task to the owner yourself in your CRM or task list

Before you start

Computer and software

  • Operating system: Windows, macOS, Linux, Browser
  • Claude Code: Current version
  • Git: Current version (to download the repository by tag)
  • Python: 3.11 or 3.12 (for Claude Ads' managed dependencies; 64-bit on Windows)

Accounts

  • An account with Claude Code access — Claude Ads is verified to work only in Claude Code. A Pro, Max, Team, Enterprise or Console account; the free claude.ai plan does not include Claude Code access
  • Atria account (optional) — An alternative to the Meta Ad Library for searching and tracking competitor ads. There is a permanent free plan (one ad account, one brand); whether competitor tracking and MCP are available on the free plan is not stated, so try it on a free account first
  • Clay account (lead path only, optional) — To import and organize the lead list. There is a free plan: the pricing page lists 200 rows per table, 500 actions and 100 data credits per month. Two other Clay documents state different limits (an older, undated FAQ: 50 rows; the sources documentation: 50,000 rows on all plans); check the limit on your own account in the table view

Step-by-step setup

Which one do you want to do?

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/8 steps.

  1. Step 1 · In a code editor

    Write down your competitors and your questions

    What for: Make it clear from the start what the observations should answer.

    1. Pick three to five competitors and create a table named 'observations.csv' in a folder. Columns: competitor, library ID, source URL, start date shown in the library, date you saw it, format (image, video), message, call to action, performance.
    2. Leave the performance column empty. Don't assume a competitor's ad works just because it appears in the library; if you have no performance data, write 'unknown'.
    3. Write down the two or three questions you want answered (e.g., which message keeps repeating, which call to action is used).

    How you know it worked

    • The folder has an observations.csv with headers ready, and your questions are written down.
    Based on: Meta: Ad Library tools
  2. Step 2 · In the browser

    Observe competitor ads in the Ad Library

    What for: Record competitors' live ads together with their sources.

    1. Open the Meta Ad Library (facebook.com/ads/library). Meta's help page says anyone can view and search the library; you can use it without creating an account. Viewing the images of age-restricted ads such as alcohol or gambling, and downloading search results, require a Facebook login.
    2. Before searching, choose the country (Turkey or the country your competitor targets) and set Ad category to 'All ads'; the default search may be political ads. Then type the competitor's page name or a keyword.
    3. For each ad, enter the library ID, URL, start date shown in the library, the date you saw it, the message, format and call to action in observations.csv. Keep what you saw and your interpretation in separate columns.
    4. The library's API is a separate tool and is meant for authorized users; this guide does not use the API.

    How you know it worked

    • Every row in observations.csv has a source URL and a date; the performance column is empty or 'unknown' when performance isn't known.
    If you get stuck: problems specific to this step
    • The competitor's ad doesn't show up in the library
      If Ad category isn't 'All ads', commercial ads won't appear; check the category and the country. If it still isn't found, the ad may not be running; the library shows active ads. Note the row as 'not found'.
    Based on: Meta: Ad Library tools, Meta Business Help Center: About Meta Ad Library (viewed October 17, 2026)
  3. Step 3 · In an app

    Optionally connect Atria to Claude

    What for: Search with Atria instead of the Library and read the workspace from Claude.

    1. Create an Atria account (there is a permanent free plan, no card required; Atria does not publish exact limits). Whether competitor tracking and MCP are available on the free plan is not stated, so first try searching the Atria library on a free account.
    2. In claude.ai, go to Settings > Connectors, add a custom connector named 'Atria', enter https://api.tryatria.com/mcp as the URL, click Add and Connect, and sign in to Atria in the window that opens. If you use Claude Code, run the command below (it is the remote MCP format from the Claude Code documentation; Atria's documentation gives no separate command for Claude Code).
    3. Connectors added in claude.ai appear in Claude Code only when you sign in with a claude.ai subscription; with an API key or Console sign-in they may not load.
    4. Again, record the ads you find in observations.csv with their source URL and date. Atria searches its own library; don't assume it is a copy of every live ad on Meta. The performance data in Atria belongs to the ad accounts you connected, not to the competitor.
    Windows · macOS · LinuxFolder: Your working folder
    › claude mcp add --transport http atria https://api.tryatria.com/mcp

    How you know it worked

    • Claude can search the Atria library; if MCP is turned off on the free plan, searching is done in Atria's web interface.
    If you get stuck: problems specific to this step
    • The connector doesn't work, or MCP calls run out sooner than expected
      Atria's sources contradict each other on MCP pricing: the pricing page lists 600 MCP calls per month on the Core plan, while a help article says MCP is currently free on every plan and uses no credits. Check your plan with Atria.
    Based on: Atria Help: Claude and ChatGPT via MCP, Atria Help: free plan, Atria pricing, Claude Code: MCP serversGet help with this step →
  4. Step 4 · In the browser

    Prepare your own ad account's export (if you have one)

    What for: So you can compare competitor observations with your own performance data.

    1. Download a CSV or JSON export from your own ad account (how to do it is on the platform's own help page). Note the date range, currency and time zone.
    2. Put the file in your working folder. Don't paste account details, keys or passwords into Claude.
    3. If you don't have an ad account, skip this step; the report relies only on your observations and does not include performance.

    How you know it worked

    • The folder contains an export file with its date range noted (or this step was deliberately skipped).
    If you get stuck: problems specific to this step
    • The export's columns aren't recognized in the analysis
      Claude Ads doesn't recognize every platform's native export format (normalization is turned off for Amazon and X); show the columns to Claude, ask it to map them, and leave anything unknown as 'unknown'.
    Based on: Claude Ads README (v2.1.0 tag)Get help with this step →
  5. Step 5 · In the terminal

    Install Claude Ads from a tagged release (only if you have an ad account)

    What for: Install the plugin that reads the ad export at a fixed version.

    You check this step yourself; the system should not move past it without your approval.

    1. If you don't have an ad account, skip this step and the next Claude Ads step; the report relies only on observations.csv.
    2. The project describes itself as a development candidate, and only Claude Code is verified; installing it is entirely optional. According to the README, a git tag is not a verified release. The verified route: download the four files on the release page (the zip, release-manifest.json, sbom.cdx.json, SHA256SUMS) into an empty folder, run the verification, and unzip only if every line says OK. The git clone below is the unverified shortcut.
    3. Verification (macOS/Linux): sha256sum -c SHA256SUMS (on macOS, shasum -a 256 -c SHA256SUMS). The README has no command for Windows; in PowerShell you can manually compare the Get-FileHash <zip> hash against the line in SHA256SUMS. This only shows the download isn't corrupted; it doesn't prove where it came from.
    4. In Windows PowerShell run .\install.ps1 -Source local; on macOS and Linux run bash install.sh --source=local. If Python 3.11/3.12 is missing or doesn't match, add -NoDeps on Windows or --no-deps on macOS/Linux to install only the plugin files (the Python helpers are not installed).
    5. The project states that its Python dependency packages have not yet been qualified with native CI on Windows and macOS; if installation gets stuck on Windows, ask for support with the error text.
    6. Open Claude Code and use /ads setup to enter your business model, goal and monthly spend. Don't enter API keys or passwords.
    7. Alternative: the README's first-listed route is the plugin marketplace (/plugin marketplace add agricidaniel/claude-ads, then /plugin install claude-ads@ai-marketing-hub-claude-ads); the command then becomes /claude-ads:ads.
    LinuxFolder: The empty folder where you downloaded the four files
    › sha256sum -c SHA256SUMS
    macOSFolder: The empty folder where you downloaded the four files
    › shasum -a 256 -c SHA256SUMS
    Windows · macOS · LinuxFolder: Your working folder
    › git clone --branch v2.1.0 --depth 1 https://github.com/AgriciDaniel/claude-ads.git

    Version pinned (as of October 16, 2026). Check the vendor documentation before moving to a newer version.

    WindowsFolder: claude-ads
    › .\install.ps1 -Source local
    WindowsFolder: claude-ads
    › .\install.ps1 -Source local -NoDeps
    macOS · LinuxFolder: claude-ads
    › bash install.sh --source=local
    macOS · LinuxFolder: claude-ads
    › bash install.sh --source=local --no-deps

    How you know it worked

    • The /ads commands appear in Claude Code, and /ads setup asks its questions.
    If you get stuck: problems specific to this step
    • Installation stops because of the Python version
      Managed dependencies require CPython 3.11 or 3.12; an unsupported version raises an error before installation. Install a suitable Python, or use -NoDeps (--no-deps) to install only the plugin files.
    • The /ads command doesn't appear
      Close and reopen Claude Code. If you installed the plugin with the marketplace command, the command may take the form /claude-ads:ads; this guide covers installing from a local copy.
    Based on: Claude Ads README (v2.1.0 tag), Claude Ads release v2.1.0 (published 2026-10-16), Claude Code: advanced setup and account requirementGet help with this step →
  6. Step 6 · In a coding agent

    Have Claude Ads analyze your own data

    What for: Surface the findings on your own ads, along with any missing data.

    1. If you don't have an ad account, skip this step. In Claude Ads this guide uses only the /ads audit command, which audits your own account's export. The plugin also has a separate /ads competitor skill that researches competitors from transparency sources (v2.1.0); this guide does not use it. You have Claude Code write the competitor report from observations.csv.
    2. In Claude Code, run /ads audit meta (or the relevant platform) and point it to the export file. The report lists passed, failed and uncheckable items with their evidence.
    3. Don't expect an account health score: scoring profiles are turned off in Claude Ads and it makes no account changes; it gives findings, unknowns and evidence coverage.
    4. For items that come back as unknown, note which data is missing.

    How you know it worked

    • The report lists passed/failed/unknown items and the missing data; there is no score and no automatic change.
    If you get stuck: problems specific to this step
    • The report doesn't give a score
      This is expected behavior: health score profiles are turned off on all platforms; read the findings and unknowns.
    Based on: Claude Ads README (v2.1.0 tag), Claude Ads capability manifest (v2.1.0 tag), Claude Ads ads-competitor skill (v2.1.0 tag)Get help with this step →
  7. Step 7 · In a coding agent

    Have the sourced comparison report written

    What for: Read your observations and your own data side by side, with their sources.

    You check this step yourself; the system should not move past it without your approval.

    1. Give Claude observations.csv and the analysis output; ask for a source URL and date next to every sentence, and for 'unknown' wherever performance isn't known.
    2. Check that you asked for what you saw (message, format, call to action) and Claude's interpretation in separate sections.
    3. Delete claims like 'this is the best ad': appearing in the library doesn't show profitability.

    How you know it worked

    • Every observation in the report has a source and date, unknown performance is flagged, and interpretations are kept separate from observations.
    Based on: Meta: Ad Library tools, Claude Ads README (v2.1.0 tag)Get help with this step →
  8. Step 8 · In an app

    Make the decision yourself

    What for: Use the report to decide; no changes are made to any account.

    You check this step yourself; the system should not move past it without your approval.

    1. Read the report and choose the ideas you'll test. If you're going to change something in your own ad, you do it yourself on the platform.
    2. Claude Ads doesn't write to your account; recommendations stay as drafts.

    How you know it worked

    • You have a list of the ideas you chose; no change was made automatically in the ad account.
    Based on: Claude Ads README (v2.1.0 tag), Claude Ads capability manifest (v2.1.0 tag)

Is the setup working? Check these

  • Every observation in the report has a source URL and date next to it; where performance is unknown it says 'unknown'.
  • If you have an ad account, Claude Ads made no changes on its own; the analysis shows findings, unknowns and missing data.
  • Every score in the lead list has a clear reason, and nothing was sent other than the tasks assigned to an owner.

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

  • SubscriptionClaude Code account

    Requires a Pro, Max, Team, Enterprise or Console account; see Anthropic's page for pricing. source

  • No costClaude Ads

    Open source and MIT-licensed; the project describes itself as a development candidate. Only for those with an ad account. source

  • No costMeta Ad Library

    Meta's page lists no fee for using the library; the API is a separate tool. source

  • SubscriptionAtria (optional)

    There is a permanent free plan; the paid Core plan is listed at $129/month billed annually. Sources contradict each other on MCP pricing: the pricing page lists 600 calls per month on Core, while a help article says MCP is currently free on every plan and uses no credits. (October 17, 2026) source

  • SubscriptionClay plan (optional)

    There is a free plan ($0 on the pricing page): 500 actions and 100 data credits per month, 200 rows per table; an older FAQ says 50 rows. Paid plan prices on Clay's page are internally inconsistent, so check there. (October 17, 2026) source

  • API usageClay enrichment usage (optional)

    Every enriched record counts as one action; purchases from data providers use data credits. Downloading a CSV uses no actions or credits. Start with a small sample. source

  • Setup serviceSetup service

    You can have us set up the analysis workflow or the connection to your existing CRM; the scope is agreed in a call.

Sources

You can set it up yourself; we can do the step you get stuck on together

Check the steps you want. The request form receives the system name and your selected steps as a visible summary that you can edit. There is no need to share any password or API key.

Steps you want help with
Discuss my setup needs Help is available with setting up the competitor observation table, installing Claude Ads and the analysis workflow, writing lead criteria, and the follow-up task workflow with your existing CRM. The exact scope and price are set in a call.

If you are looking for another route

The guide is free and needs no sign-up; you can follow the steps here yourself. If you’d like professional support at some point, choose the option that fits your needs. This doesn’t affect the rankings in the guide.