Akademie für Lernpädagogik
Educational Research Center
+2.7K new ads€7.4M
AdSpends MCP
Ask Codex
Connect AdSpends to Codex, Claude, ChatGPT, Cursor or Gemini. Search Meta ads, inspect brands and break down landing pages, ranked by estimated EU ad spend.
codex — ~/brand-research
>_ OpenAI Codex
directory: ~/brand-research
mcp: adspends
› Show me the top Meta ads in Germany this week
• Called adspends.search_ads({…})
└ 3 results
•Here are the top Meta ads in Germany this week, ranked by estimated EU ad spend:
1
384.339€
13M
100
JYSK Deutschland
4d
Tolle skandinavische Weihnachtsangebote – Mach dich bereit für unsere Weihnachtsangebote und bringe festliche Stimmung in dein Zuhause
jysk.de
Spare bis zu 60%
2
27.059€
902K
100
Amazon Prime Video
3d
Tauche ein in Dexter: Wiedererwachen, jetzt zum Streamen auf Prime Video mit einem Paramount+ Abo verfügbar.
amazon.de
Dexter ist zurück
3
26.286€
876K
100
Koriderm
6d
Say goodbye to wrinkles with this all-in-one skincare solution 👋
koriderm.com
Buy 1 Get 1 Free Today Only!
›
Ask Codex to do anything
⏎ send · ⇧⏎ newline · adspends connected
How to connect AdSpends to Codex in 3 steps
Create a key, add the server, ask. Create an AdSpends API key, add three lines to ~/.codex/config.toml, then ask Codex about ads, brands and landing pages. Setup takes under a minute.
Add AdSpends to config.toml
Paste this into ~/.codex/config.toml and replace the placeholder with your API key. The Codex CLI, the IDE extension and Codex in the ChatGPT desktop app all read this file, so you set it up once. You get the full toolset: ads, brands, landing pages and your saved boards.
~/.codex/config.toml
[mcp_servers.adspends]
url = "https://app.adspends.com/api/mcp"
http_headers = { "Authorization" = "Bearer <YOUR_API_KEY>" }Codex sends your AdSpends API key as a Bearer header. Create and revoke keys at app.adspends.com/mcp.
Create your API key →Prefer keeping the key out of the file? Replace the http_headers line with bearer_token_env_var = "ADSPENDS_API_KEY" and export the key in your shell. For a single project, use .codex/config.toml in a trusted project instead.
You can also add AdSpends from the MCP servers settings in the IDE extension or the ChatGPT desktop app: choose Streamable HTTP and paste the AdSpends MCP link. config.toml is the quickest way to include your API key.
- 1
Create a key
Sign in at app.adspends.com/mcp and create an API key. The free trial works too.
- 2
Add the server
Paste the [mcp_servers.adspends] entry into ~/.codex/config.toml with your key and save. Restart Codex if it is running.
- 3
Ask
Type /mcp in the Codex CLI to see AdSpends connected, then ask in plain English. Codex picks the tools and pulls the data.
Data is updated daily, and the free trial includes 100 API credits.
Can Codex see Meta ads on its own?
No. Codex has no access to Meta’s Ad Library, and web search finds articles about ads, not the ads themselves. The Meta Ad Library shows ads one brand at a time, with spend only for political ads. AdSpends gives Codex the ads, the spend estimates and the landing pages behind them.
| Feature | Codex alone | Meta Ad Library | Codex + AdSpends |
|---|---|---|---|
| Meta ads | No access. Web search finds articles about ads | Search by brand or keyword in the browser | Searches 9.2M Meta ads from the chat |
| Ad spend | Guesses | Only for political and social issue ads | Estimated EUR spend for every ad delivered in the EU |
| Find the winners | Not possible | No sorting by spend or reach | Ranks ads, brands and landing pages by spend and reach |
| Landing pages | Only pages you paste in | Link only | Full page text, page type and the ads pointing to it |
| Video ads | Can’t watch them | Watch one by one | Timestamped transcripts Codex can read and rewrite |
| Competitor overview | Not possible | Scroll through every ad yourself | Spend, new ads, top ads and top pages in one answer |
| Your research | Not available | Not available | Your saved boards and tracked brands |
Codex can’t see Meta’s Ad Library. Now it can.
Give Codex 9.2M Meta ads and the funnel behind each one
Ask what your market is running. Codex gets back the ad, the brand running it, its estimated EU ad spend and the landing page it sends traffic to.
9.2M
Meta ads
Every Facebook and Instagram ad delivered in the EU, searchable by copy, format, platform and run time.
849k
Brands
Every brand advertising in the EU, ranked by estimated spend, reach and new ads.
739k
Landing pages
Advertorials, quizzes and sales pages, sorted by how many new ads point to them.
Everything Codex reads, record by record
Not just a link to the Ad Library. Every ad, brand and landing page arrives with the data behind it.
Every ad
8 data points
Ad copy and CTA
Primary text and the call-to-action button.
Image and video creative
The original creative file, ready to view.
Video transcriptTimestamped
Spoken text with timestamps, language and duration.
Estimated ad spend
EU reach and spend in EUR for each ad.
Run time and status
First seen date and whether it is still running.
Platforms
Facebook, Instagram, Messenger, Audience Network, Threads.
Destination URL
The landing page the ad sends traffic to.
Performance rank
A 0–100 score to compare ads at a glance.
Every brand
6 data points
Total estimated spend
Spend in EUR and EU reach across all ads.
Total, active and new ads
New ads in the last 30 days show who is scaling.
Top ads and top landing pages
The brand’s winners by EU reach, in one answer.
Market, category and niche
Where the brand sits, to find its competitors.
Social following
Facebook likes, Instagram followers and profiles.
Advertising history
When the brand was first seen running Meta ads.
Every landing page
7 data points
Full page text as MarkdownMarkdown
Headlines, body copy and offer, up to 20,000 characters.
Page typeAI-classified
Advertorial, quiz, VSL, listicle, PDP, offer page, comparison or shop.
Full-page screenshot
See the layout, not just the words.
Ads sending traffic
Total, active and new ads in the last 30 days.
Spend and share of brand spend
How much of the brand’s budget flows here.
Language and tech stack
Page language and the tools the page is built with.
First and last seen
How long the page has been live in ads.
What can Codex do with AdSpends?
15 things marketers ask Codex once AdSpends is connected: find the ads making money, look inside competitors’ accounts, break down their funnels and turn it all into briefs. Copy any prompt and paste it into Codex.
Find winning ads1–3
Skip the guessing. Start from ads with real spend behind them.
Find the ads making money in your niche
Every Meta ad in a niche, ranked by estimated EU ad spend, with creative, copy and landing page.
Ask Codex
“Show me the 20 highest-spend skincare ads in Germany from the last 30 days.”
search_ads
Spot winners before they peak
New ads that already pull big reach are the ones brands are scaling right now.
Ask Codex
“Which supplement ads launched in the last 14 days already have the most reach? Show me the top 10.”
search_ads
Map every angle in a market
Codex reads hundreds of ads and sorts them into angles, pain points and offers, weighted by spend.
Ask Codex
“List the angles and pain points weight loss brands in France spend the most on, ranked by estimated spend.”
search_ads
Hooks, scripts and briefs4–6
Turn winning ads into the next creative you test.
Group hooks by what’s scaling
Not a pile of saved ads, the pattern behind them. See which openings carry the most spend.
Ask Codex
“Pull the top 30 sleep supplement video ads and group their opening hooks into 5 patterns, ranked by spend.”
search_adsget_ad
Rewrite winning video scripts
Timestamped transcripts of the top video ads, ready to rework for your product.
Ask Codex
“Get the transcripts of the 3 best collagen video ads and write 3 new scripts for my brand with the same structure.”
get_ad
Get the first draft of every brief
Headlines, hooks, reference ads and landing pages from real winners, in your brief template.
Ask Codex
“Write a creative brief for a magnesium launch: 10 hooks, 5 headlines, 3 reference ads and 2 landing pages.”
search_adssearch_landing_pages
Spy on competitors7–9
As if you had access to their Business Manager.
See what a competitor really spends
Estimated spend, active and new ads, top creatives and where the traffic goes, in one answer.
Ask Codex
“How much is MORE Nutrition spending on Meta, which ads are scaling and which landing pages get the traffic?”
get_brand_overview
Find brands that are scaling right now
Brands launching the most new ads are the ones that found something that works.
Ask Codex
“Which beauty brands launched the most new Meta ads in the last 30 days?”
search_advertisers
Catch every new launch
New creatives, offers and angles from any brand, newest first, the week they go live.
Ask Codex
“What did my 3 biggest competitors launch on Meta this week? Summarize the new angles and offers.”
search_advertisersget_advertiser_ads
Landing pages and funnels10–12
Stop sending ads to a basic product page.
Find the advertorials with the most spend
Advertorials, listicles, quizzes and VSLs, sorted by the spend behind them, with full page text.
Ask Codex
“Show me the joint pain advertorials with the most ad spend and outline the structure of the top one.”
search_landing_pagesget_landing_page
Reverse-engineer a competitor’s funnel
See which page types a brand runs, which ads feed them and how its budget splits.
Ask Codex
“Break down the funnel of Bears with Benefits: which page types they use and how much spend goes to each.”
get_brand_overviewget_landing_page
Compare offers and guarantees
Search pages by the words on them, then compare prices, bundles, guarantees and claims.
Ask Codex
“Find hair loss landing pages that mention a money-back guarantee and compare their offers in a table.”
search_landing_pages
Reports on autopilot13–15
Hours of research every week, done in one prompt.
A Monday report on your tracked brands
What the brands you track launched last week and which of their ads got the most reach.
Ask Codex
“Give me a Monday report: what my tracked brands launched last week and their 5 biggest new ads.”
list_tracked_brandsget_advertiser_ads
Turn your swipe file into insights
Codex reads your saved boards and tells you what your best saved ads have in common.
Ask Codex
“Summarize my “Q4 Hooks” board: which saved ads have the most spend and what do they have in common?”
get_saved_board_adsget_board_statistics
Pitch clients with real market data
Agencies build a market report for a prospect in minutes: top spenders, best ads, best pages.
Ask Codex
“Build a market report for a pet food prospect: top 10 spenders in Germany, their best ads and landing pages.”
search_advertisersget_brand_overview
What is the AdSpends MCP?
The AdSpends MCP is a Model Context Protocol server that gives Codex read access to the AdSpends Meta ads database. MCP is the standard way AI agents plug into the apps you use, so Codex can search ads, brands and landing pages and write the results straight into your project.
How Codex uses AdSpends
- Add the AdSpends server to ~/.codex/config.toml with your API key
- Codex discovers the AdSpends tools when it starts
- It picks the right tool for your task: ads, brands or landing pages
- It writes the brief, report, data file or landing page code you asked for
- The same setup works in the CLI, the IDE extension and the ChatGPT desktop app
~/.codex/config.toml
[mcp_servers.adspends]
url = "https://app.adspends.com/api/mcp"
http_headers = { "Authorization" = "Bearer <YOUR_API_KEY>" }
# Ads: search_ads, get_ad
# Brands: search_advertisers, get_advertiser,
# get_brand_overview, get_advertiser_ads
# Landing pages: search_landing_pages, get_landing_page
# Your saved data: list_saved_boards, get_saved_board_ads,
# list_tracked_brands, ...
# Lookups (free): list_markets, list_categories,
# list_niches, get_usageWhich markets and platforms can Codex research?
Every Meta ad delivered in the EU, across every placement Meta reports. Codex can narrow any question down by market, niche, platform, format and ad language.
Markets24
Every brand is sorted into a market, so Codex can compare it with its real competitors.
- Health & Supplements
- Beauty & Skincare
- Fashion
- Jewelry
- Home & Garden
- Home Decor
- Furniture
- Kitchen
- Food & Drink
- Pet Supplies
- Baby & Kids
- Sports & Outdoors
- Electronics & Tech
- Software
- Gaming
- Toys & Games
- Books & Education
- Finance & Insurance
- Real Estate
- Travel & Tourism
- Automotive
- Retail
- Entertainment
- Agency & Consulting
Meta platforms
Every placement Meta reports reach for.
- Messenger
- Audience Network
- Threads
Ad formats
Ask for one format or compare them.
- Image ads
- Video ads
- Carousel ads
Landing page types
Classified by AI, so Codex can ask for one type.
- Advertorials
- Listicles
- Quizzes
- VSLs
- Product pages
- Offer pages
- Comparison pages
- Shops
Deepest coverage in Germany and DACH
Ask in English, and Codex still searches ads written in any EU language.
- German
- French
- Spanish
- Italian
- Dutch
- Polish
- All EU languages
Connect any AI tool to AdSpends
One MCP server, one account, the same credits. Pick the tool you already work in.
Pricing, security and troubleshooting
How much does it cost?
The Codex connection has no separate charge. The free trial includes 100 API credits, and every paid plan includes 2,000 to 30,000 credits per month. Searches cost 1 credit per result, detail lookups 1 to 5 credits, and lookups like markets, niches and usage are free.
See plans & pricing →How is access secured?
Codex authenticates with an AdSpends API key that you can revoke at any time at app.adspends.com/mcp. The server is read-only, so Codex can’t change your boards or trigger anything. Keep config.toml private, or read the key from an environment variable with bearer_token_env_var.
Something not working?
Codex answers without using AdSpends
Type /mcp to check that AdSpends is listed, or start your prompt with “Use AdSpends to…”.
AdSpends fails to start or returns 401
Check that the header reads “Bearer ” followed by your key and that your trial or plan is active, then restart Codex.
Codex says I’m out of credits
Ask Codex to check your AdSpends usage (free). Credits reset monthly, and credit packs top you up instantly.
The IDE extension doesn’t show AdSpends
The extension reads the same ~/.codex/config.toml. Open its MCP servers settings and restart the extension after editing the file.
FAQ
How do I connect AdSpends to Codex?
Create an API key at app.adspends.com/mcp, then add an [mcp_servers.adspends] table to ~/.codex/config.toml with url = "https://app.adspends.com/api/mcp" and an Authorization header of “Bearer <YOUR_API_KEY>”. Restart Codex and type /mcp to check the connection.
What can Codex do with AdSpends?
Codex can search 9.2M Meta ads, 849k brands and 739k landing pages, rank them by estimated ad spend, pull brand overviews with top ads and landing pages, and read your saved boards and tracked brands. It turns the results into markdown briefs, CSV files, reports and landing page code inside your project.
Can Codex search the Meta Ad Library on its own?
No. Codex has no access to the Meta Ad Library, and web search finds articles about ads rather than the ads themselves. With the AdSpends MCP server, Codex searches Facebook and Instagram ads directly, with estimated ad spend, video transcripts and the landing pages each ad sends traffic to.
Does it work in the Codex IDE extension and the ChatGPT desktop app?
Yes. The Codex CLI, the IDE extension and Codex in the ChatGPT desktop app share ~/.codex/config.toml, so AdSpends shows up in all of them after one setup. You can also add it from their MCP servers settings as a Streamable HTTP server.
Is Codex the same as ChatGPT?
No. Codex is OpenAI’s coding agent and reads AdSpends from config.toml with an API key. In the ChatGPT chat on the web, you add AdSpends under Plugins and sign in instead; the setup is on the AdSpends for ChatGPT page. Both use the same server (https://app.adspends.com/api/mcp), account and credits.
Can Codex run AdSpends reports on a schedule?
Yes. codex exec runs a prompt without the interactive UI, so a cron job or CI workflow can write a weekly competitor report to a file. For fully custom automations, the same data is available through the AdSpends REST API.
Which markets and countries does AdSpends cover?
AdSpends covers Meta ads delivered in the EU, because the reach data comes from Meta’s EU transparency reporting. Coverage is deepest in Germany and the DACH region. Brands are grouped into markets such as Health & Supplements, Beauty & Skincare, Fashion, Home & Garden and Pet Supplies, and ads can be filtered by language, platform and format.
Where does the data come from?
From the Meta Ad Library. AdSpends collects Facebook and Instagram ads delivered in the EU every day, together with the reach Meta publishes under the Digital Services Act, and links them to brands and landing pages.
How is the ad spend calculated?
Ad spend is an estimate in EUR, calculated from the EU reach that Meta publishes at a €30 CPM. It is built for comparing ads, brands and landing pages with each other, not as an exact invoice.
Is it free to use AdSpends with Codex?
There is no separate charge for the Codex connection. Every AdSpends plan includes 2,000 to 30,000 API credits per month, and the free trial includes 100.
Is it safe to connect AdSpends to Codex?
Yes. The server is read-only, your API key can be revoked at any time at app.adspends.com/mcp, and your saved boards are only visible to your own account.
Give Codex real Meta ads data
Start the free trial, add three lines to config.toml and ask your first question.
Start free trial