Claude Code
Version 2.1.186 or later. Run once, then sign in when the browser opens.
claude mcp add --transport http --scope user adspy 'https://www.adspy.sh/mcp' && claude mcp login adspymcp
Adspy MCP: research Meta and Google ads from Claude or Codex
The Adspy MCP server connects Claude, Claude Code, Codex and other remote MCP clients to Adspy's library of public Meta and Google ads and to brands' organic TikTok, YouTube and Instagram posts, with 31 tools to search creatives, read analysis, read social posts, run a Brand Full Analysis, fetch brands and accounts, and save to collections. It works on every plan, from $19/month for one source and $39 for all three: browsing is included, and each paid result says its price.
- Endpoint
- www.adspy.sh/mcpStreamable HTTP, sign-in with OAuth
- Clients
- Claude, Claude Code and CodexAnd any remote MCP client; ChatGPT and Cursor coming soon
- Tools
- 31 tools23 of them free or included
- Credits
- 2,000 or 6,000 a month, or no countStarter $19, Pro $39 and Unlimited $99
claude mcp add --transport http --scope user adspy 'https://www.adspy.sh/mcp' && claude mcp login adspy
- get_context{}Free0
- search_creatives{ query: "protein", platform: "meta", format: "video", limit: 20 }Included0
- get_creative_analysis{ hashes: [5 creatives from the search] }Included0
- get_brand_full_analysis{ brandKey: [a brand from the search], range: "90d" }90 credits90
- save_creatives{ name: "Q4 hooks", hashes: [3 creatives] }Free90
Session, at most90 creditsof 2,000 a month on Starter
How do you connect Adspy to your AI assistant?
Adspy's MCP server lives at https://www.adspy.sh/mcp. Claude Code and Codex add it with one command, Claude on the web, desktop or mobile adds it as a custom connector, and any other remote MCP client takes the URL. Each client then opens Adspy's sign-in in the browser, where you choose the workspace and the spending limit for that connection.
Codex
Run once, then sign in when the browser opens.
codex mcp add adspy --url 'https://www.adspy.sh/mcp' && codex mcp login adspyClaude on the web or desktop
Customize, Connectors, Add custom connector. Paste the endpoint; no client ID, secret or API key is needed.
https://www.adspy.sh/mcpWhich tools does the Adspy MCP server provide?
The Adspy MCP server provides 31 tools, from checking the connection to exporting research. 23 of them are free or included: browsing ads, posts and their analyses costs no credits, with fair use. The others charge credits for results: a Brand Full Analysis or a report, reused free for 24 hours, a comparison, and a new brand or account.
| Tool | What it does | Credits | Changes your workspace |
|---|---|---|---|
| Start | |||
get_context | Checks the connection: workspace, permissions, credit balance and limits. | Free | No |
list_playbooks | Shows ready research jobs by goal, each with its steps, its price and a prompt to run. | Free | No |
quote_operation | Returns the most a paid call can cost before it runs. | Free | No |
get_usage | Shows the organization's balance and receipts. | Free | No |
| Find | |||
search_brands | Finds brands in the library by name. | Free | No |
search_advertisers | Looks a brand up in Meta Ad Library and Google Ads Transparency. | Free | No |
search_creatives | Searches ads with scopes, filters, AI tags and a sort order. | Included | No |
find_similar_creatives | Finds other brands' ads that share specific AI tags. | Included | No |
| Read | |||
get_creatives | Returns creatives with their source ads and existing transcripts. | Included | No |
get_creative_analysis | Returns an ad's stored AI reading; an ad without one says so. | Included | No |
get_brand_xray | Runs Brand X-Ray for one brand and range; reused free for 24 hours. | 60 credits | No |
get_brand_full_analysis | Reads one brand's ads, organic posts and how they connect, each finding with its sample size and 95% interval; reused free for 24 hours, with the brand's social report. | 90 credits | No |
compare_brands | Compares two to five brands on the same range. | Up to 60 credits per brand | No |
| Fetch | |||
request_brand_fetch | Adds a missing Meta or Google advertiser to the library once you say yes; its 20 newest ads come with it. | 400 credits, new requests only | Yes |
get_fetch_job | Reads a fetch's stage and the ads or posts processed. | Free | No |
| Social posts | |||
search_social_accounts | Finds a brand's TikTok, YouTube or Instagram account. | Free | No |
request_social_fetch | Collects the organic posts of a TikTok, YouTube or Instagram account once you say yes; its 20 latest come with it. | 400 credits, 0 for an account Adspy already collects | Yes |
list_social_posts | Lists a brand's organic posts by date, engagement or breakouts, with paid reach apart. | Included | No |
get_social_posts | Reads posts in detail: snapshots, the ads that reused them and AI tags. | Included | No |
find_posts_run_as_ads | Pairs a brand's organic posts with the ads that reused them. | Included | No |
get_brand_social | Reports a brand's engagement, cadence, formats, breakouts and paid reach. | 60 credits, reused for 24 hours | No |
compare_social | Compares two to five brands' organic posts with verdicts and their sample sizes. | Up to 60 credits per brand | No |
| Keep | |||
list_collections | Lists the workspace's collections. | Free | No |
get_collection | Reads a collection's saved ads and notes. | Included | No |
save_creatives | Saves ads to a collection, or creates one by name. | Free | Yes |
update_note | Writes the note on a saved ad. | Free | Yes |
follow_brand | Follows a brand in the workspace. | Free | Yes |
| Export | |||
export_research | Exports ads, social posts, post-ad pairs, reports and comparisons to CSV, Excel, JSON or a ZIP of media; ads also to Markdown or HTML, reports and comparisons to PDF. | Included; a report not read in 24 hours, 60 credits per brand | No |
get_job | Reads an export's progress and its download link. | Free | No |
list_exports | Lists your exports from the last 7 days. | Free | No |
renew_delivery_links | Renews media links from an earlier result; links last 21 days. | Free | No |
How do credits and spending limits work?
Adspy includes browsing on every plan and charges results in credits: on Starter and Pro, from your organization's monthly credits (2,000 or 6,000); Unlimited has no credit count, and fair use applies. A session that reads 20 ads and 5 analyses, runs one Brand Full Analysis, compares 2 brands and adds one new brand costs 610 credits on Starter or Pro, where each connection carries its own spending limit for paid results.
610 credits for one session
- 0 for 20 ads and 5 analyses, included
- 90 for one Brand Full Analysis
- 120 for a comparison of 2 brands
- 400 for one new brand
That is 30.5% of Starter’s 2,000 monthly credits.
| Limit | What it allows |
|---|---|
| Plan credits (default) | Up to the plan's monthly allowance; up to 400 credits per request |
| Small budget | 500 credits a month; up to 100 per request |
| Browse only | Browsing included, no paid results |
| Custom | Your own monthly and per-request caps |
What does Adspy show inside the assistant?
Adspy shows its results inside Claude as a research gallery, next to the assistant's answer. You can select ads, open a reading, save a selection or quote an export there, browse a brand's organic posts, and every paid action shows its credits on the button.
- Gallery
- The ads from a search, a similar-ads call or a collection, with carousels and one video playing at a time.
- Social posts
- A brand's organic TikTok, YouTube and Instagram posts, the posts it later ran as ads and its social report, on cards like the ad cards, marked when a post broke out, drew paid reach or ran as an ad.
- Analyze selected
- Opens the readings of the selected ads, included on every plan.
- Save
- Saves the selection to a new or existing collection, with a note editor on each ad.
- Detail
- The ad's media and copy, its transcript and full analysis, and its source ads.
- Export
- Quotes and runs an export as CSV, Excel, JSON, Markdown, HTML, PDF or a ZIP of media, with or without analysis.
- Quotes
- A paid action above the connection's limit waits for an organization admin to approve it on the website.
What can you ask Adspy from your assistant?
Adspy answers research requests in plain words: the assistant picks the tools, says the price of a paid result and cites the ads it found. These requests use the tools listed next to them.
“Find 20 recent Meta video ads from Huel that mention protein.”
search_brandssearch_creativesPlaybookKeep watch on a competitor's new ads“Read the hook and call to action of the five ads I picked.”
get_creative_analysisPlaybookTake one ad apart“Run a Brand Full Analysis of AG1 over the last 90 days, then compare its ads with Huel's and Grüns'.”
get_brand_full_analysiscompare_brandsPlaybookPrepare a pitch or a creative audit“Find ads from other brands that open like this one.”
find_similar_creativesPlaybookTake one ad apart“This brand is missing: find its Meta advertiser and add it.”
search_advertisersrequest_brand_fetchget_fetch_jobPlaybookAdd a brand Adspy does not have yet“Show me Gymshark's TikTok posts that broke out this quarter, and which of them later ran as ads.”
search_social_accountsrequest_social_fetchlist_social_postsfind_posts_run_as_adsPlaybookSee what a brand posts on TikTok, YouTube and Instagram“Save the three strongest openings to my Q4 collection with a note on each.”
save_creativesupdate_notePlaybookBuild a swipe file
How to set up Adspy in your assistant
Adspy's MCP server is set up once per person in Claude, Claude Code, Codex or any remote MCP client. Every research request then runs in the assistant: browsing is included, the assistant asks before adding a new brand or account, and other paid results say their price once. The Adspy website keeps the account side: the plan, the credit balance, each connection's spending limit and the approvals.
In your AI assistant
- Claude on the web, desktop or mobile: open Customize, then Connectors, choose Add custom connector, name it Adspy and paste https://www.adspy.sh/mcp, then sign in to Adspy and approve the connection.
- Claude Code: claude mcp add --transport http --scope user adspy 'https://www.adspy.sh/mcp' && claude mcp login adspy
- Codex: codex mcp add adspy --url 'https://www.adspy.sh/mcp' && codex mcp login adspy
- Any other remote MCP client: add https://www.adspy.sh/mcp as a Streamable HTTP server; it opens Adspy's sign-in through OAuth, with no key to paste.
- Ask the assistant to run get_context first: it confirms the workspace, permissions and balance, for free.
- The setup guide shows the steps for each client. ChatGPT and Cursor are coming soon.
What the Adspy MCP server does not do
No free plan
The MCP server needs a paid plan: Starter ($19/month), Pro ($39/month), Unlimited ($99/month) or Enterprise on contract. Adspy has no free plan or trial.
One source on Starter
Starter covers one source: Meta, Google or TikTok; Pro and above cover every source. A brand's ads and posts on another source need Pro, from $39/month.
No spend or ROAS
The tools return public ads and their recorded activity and analysis, and the public counts of organic posts. They have no spend, reach or conversion data, and assistants should not infer any.
No TikTok ads
The tools cover Meta and Google ads and the organic posts of brands' TikTok, YouTube and Instagram accounts. TikTok ads are not covered.
No surprise charges
Browsing costs no credits. The assistant asks before adding a new brand or account; other paid results say their price, stay within the connection's limit and wait for an admin's approval above it. Top-ups are not sold; the allowance renews each month.
Viewers read only
A viewer's connection can read but not save, follow or fetch. Writing needs a member, admin or owner.
Questions about Adspy MCP
Which assistants work with Adspy?
Claude, Claude Code, Codex and any other remote MCP client, with the setup shown on this page. ChatGPT and Cursor are coming soon. The server follows the MCP standard over Streamable HTTP with OAuth sign-in.
What costs credits, and what is included?
Browsing is included on every plan, with fair use: searching and opening ads with their AI analysis, similar ads, collections, a brand's organic posts with their AI tags, posts run as ads, and files of them cost no credits. Credits pay for results only: a Brand Full Analysis (90 credits per brand and range), a social report, a Brand X-Ray or each brand in a comparison (60 credits), and a new brand or social account (400 credits). A report is free again for 24 hours. On Starter and Pro, reading past fair use costs 1 credit per new item until the limit resets; on Unlimited, new items wait for the reset.
Can my team share the credits?
Yes. Credits belong to the team: everyone in the organization draws on the same monthly allowance, and an extra user adds no credits. An extra user is $5 a month on Starter, $15 on Pro and $29 on Unlimited. Each person connects with their own limit.
What is the difference between Starter, Pro and Unlimited?
Every plan gives the assistant the same 31 tools; they differ in sources and credits. Starter ($19 a month) covers one source of Meta, Google or TikTok, with 2,000 credits a month; Pro ($39) covers every source, with 6,000; Unlimited ($99) covers every source with no credit count, and fair use applies. Enterprise, on contract, adds a REST API with API keys, limits set in the contract and invoice billing; Instagram is not in the API.
What happens to credits I do not use?
Included credits reset at the end of each billing period; they do not carry over.
Sources and method
The tool list, purposes and costs come from the server's own tool definitions and the published credit tariff; a test fails if a tool is added or removed without this page changing.
The session example adds up the published tariff: 20 ads and 5 analyses at 0 (browsing is included), one Brand Full Analysis at 90, a comparison of 2 brands at 60 per brand and one new brand at 400.
Corrections: info@adspy.sh
Have a brand in mind?
Add Adspy to your assistant with this URL, sign in, and ask about its ads. Connecting takes a few minutes, and no ad account.
Connect your AI
https://www.adspy.sh/mcp