Connect Claude Code, Codex or Cursor to Meta's Ad Library
Connect vexqo's MCP server to your coding agent and ask what any brand runs on Meta: its offers, its messages and when they ran. Setup is one command or one small file.
One question, answered from the library
We asked Claude Code what Gymshark ran in the UK for Black Friday last year. It made two tool calls and answered in about half a minute.
What did Gymshark run on Meta in the UK for Black Friday last year? Tell me the offers and the angles.
I'll start by finding Gymshark's page ID.
search_meta_adsq: "Gymshark" · country: "GB" · active_status: "all" · limit: 55 of 41,681 ads · 4.5 s · 1 creditPage ID is 129669023798560. Now I'll pull its ads that started around Black Friday 2025.
search_meta_adspage_id: "129669023798560" · country: "GB" · active_status: "all" · start_date: "2025-11-01" · end_date: "2025-12-02" · limit: 3030 of 991 ads · 3.2 s · 3 creditsGymshark's UK Black Friday 2025 ads on Meta ran from 18 November to about 3 December. The offer stepped up in stages.
- 18 NovBlack Friday Sale, up to 50% off everythingExtra 10% with WELCOME10, shown in some ads
- 21 to 24 NovSame sale, up to 50% offNew-customer ads used NEW15 for an extra 15%
- 22 Nov"Time for heavy gifting": up to 50% off, plus free returns extended to 31 Jan 2026
- 27 to 28 NovUp to 50% off, plus an extra 25% off everythingEXTRA25
- 30 Nov"Ends soon" last-chance push: up to 50% off, plus an extra 25%Code (the ad text cuts off before naming it)
The sample leaves out lower-impression ads. There may be other offers or codes in the remaining ~960 ads.
A real session in Claude Code 2.1.322 with Claude Sonnet 5.5, recorded on 20 November 2026. The seconds are the ones each call took. The answer is shortened.
What it found: Gymshark's Black Friday approach
All 30 ads offered up to 50% off. What changed was the extra code on top, which grew as Black Friday came closer, and the message around it.
When each offer and message ran, across the 30 ads
Headline
Extra code on top
WELCOME104 adsNEW151 adEXTRA257 adsMessage
A bar runs from the day the first ad with that line started to the day the last one ended. An ad can count in more than one row. Four of the seven 25% ads name the code.
It started ten days early
The first of these ads started on 18 November. Black Friday was the 28th.
One headline, a growing code
Every ad offered up to 50% off. The code on top went from 10% to 15% to 25%.
The codes handed over
The 15% code started on 24 November, a day before the last 10% ad ended. The 25% code started on the 27th, the 15% ad's last day.
Messages piled up near the day
Gifting ran from 22 November, payday from the 28th and "ends soon" from the 30th, each on top of up to 50% off. Each ad ran for 3 to 9 days.
Each agent put it in its own words. Claude Code: "The offer stepped up in stages." Cursor: "a stacked discount ladder, not a single offer". Codex: "up to 50% off, boosted by NEW15 early in the week and EXTRA25 for Black Friday weekend/payday".
This reading comes from 30 of the 991 ads that ran in that period, the ones with the most impressions. The library does not show spend or sales, so it tells you what Gymshark ran and not what worked. Black Friday 2026 is on 27 November: ask the same question about your own competitors.
Why this question is a fair test
It needs last year's ads
No model remembers which ads a brand ran in one week of November 2025. The answer has to come from the library.
It needs a period
The agent chose the settings by itself: the UK, 1 November to 2 December 2025, ads running or stopped.
An assistant cannot fetch it
Meta turns AI crawlers away from the library. We checked how.
It has an edge you should know
Meta keeps stopped ads for a year where they ran in the EU or the UK. For a brand that advertises only in the US, the same question comes back empty.
Set it up
Pick your agent. Each one needs two things: the server's address, https://api.vexqo.dev/mcp, and your API key.
Your connection
Claude Code
One command adds the server for every project on your machine.
- Get an API key. The trial is free and has 500 credits.
- Run the command below in a terminal, with your key in place of
YOUR_KEY. - Start Claude Code and type
/mcp. vexqo should show five tools.
claude mcp add --transport http --scope user vexqo https://api.vexqo.dev/mcp \
--header "X-API-Key: YOUR_KEY"
To share the server with one project, put this file at its root and set VEXQO_API_KEY in your shell. The key stays out of the file.
{
"mcpServers": {
"vexqo": {
"type": "http",
"url": "https://api.vexqo.dev/mcp",
"headers": {
"X-API-Key": "${VEXQO_API_KEY}"
}
}
}
}
Your connection
Codex
Codex reads the key from an environment variable, so it never sits in the configuration.
- Get an API key. The trial is free and has 500 credits.
- Run the two lines below in a terminal, with your key in place of
YOUR_KEY. Add the first line to your shell profile so it lasts. - Start Codex and ask your question. It lists vexqo among its MCP servers.
export VEXQO_API_KEY="YOUR_KEY"
codex mcp add vexqo --url https://api.vexqo.dev/mcp \
--bearer-token-env-var VEXQO_API_KEY
The second line writes this to ~/.codex/config.toml. You can add it by hand.
[mcp_servers.vexqo]
url = "https://api.vexqo.dev/mcp"
bearer_token_env_var = "VEXQO_API_KEY"
Your connection
Cursor
Open the install dialog with one click, or add the configuration by hand.
- Get an API key. The trial is free and has 500 credits.
- Choose Add to Cursor and put your key in place of
YOUR_KEYin the dialog. Or put the configuration below in~/.cursor/mcp.json. - Open the MCP page of Cursor's settings. vexqo should show five tools. Approve the first call when the chat asks.
{
"mcpServers": {
"vexqo": {
"url": "https://api.vexqo.dev/mcp",
"headers": {
"X-API-Key": "YOUR_KEY"
}
}
}
}
Cursor's command-line agent refuses a tool call nobody approved. Allow these with "Mcp(vexqo:*)" in the permissions of .cursor/cli.json.
The five tools your agent gets
A tool call costs the same credits as the API request behind it, and every answer says what it cost.
| Tool | What it returns | Credits |
|---|---|---|
search_meta_ads | Up to 30 ads for a keyword or an advertiser, with the library's total and a cursor for more | 1 for every 10 ads |
get_meta_ad | One ad whole: its full text, every card, its media links and the details panel | 2 |
search_ebay_listings | One page of eBay results for a keyword | 1 for every 15 results |
get_ebay_listing | One eBay listing: price, condition, seller, shipping and item specifics | 4 |
get_account | The credits left, the limits, the prices and the usage of the last 30 days | Free |
Questions to try first
What did Gymshark run on Meta in the UK for Black Friday last year? Tell me the offers and the angles.
Which ads did Sephora start in the US this week? Group them by angle.
Search Meta ads for "running shoes" in Germany and list the ten advertisers that appear most.
All three answered it
We asked each agent the Gymshark question on 20 November 2026. The time depends on how much the agent decides to read.
| Agent | What it read | Time |
|---|---|---|
| Claude Code 2.1.322 | 2 searches | 31.5 s |
| Cursor, command-line agent | 2 searches and 5 whole ads | 202 s |
| Codex 0.166.0 | 17 searches and 9 whole ads | 571 s |
What to know before you rely on it
History depends on the country
A past period works where Meta keeps stopped ads, the EU and the UK. Elsewhere the library holds only ads that are running.
30 ads a call
A search returns 10 ads unless the agent asks for more, 30 at most, and a cursor reads on.
Whole ads are slower
Reading one ad in full takes longer than a search. Ask for it when you need the full text or the media.
No spend, no sales
The library shows what a brand ran and when. It does not show what the ads cost or earned.
Ask about your own competitors
The trial is free and has 500 credits. The session above cost 4.
Get an API key