Ads MCP for Claude Code: setup, cursors and scheduling
Set up Proxy's ads MCP in Claude Code: the one-line install, sign-in with /mcp, how large ad lists are windowed with free cursors, and weekly scheduling.
Claude Code runs Proxy from the terminal and can write what it finds into your repo. One connection gives it all four ad libraries: Meta, Google, LinkedIn and TikTok (EU).
Connect
-
Add the server:
claude mcp add --transport http proxy 'https://mcp.useproxy.dev/mcp?ref=docs' -
Run
/mcpinside Claude Code and sign in toproxy. -
Restart Claude Code.
-
When it asks to run a Proxy tool, choose Yes, and don’t ask again. Every Proxy tool is read-only.
Or use the installer. It signs you in once and writes the config:
curl -sL useproxy.dev/install | sh
Pick Claude Code when asked.
How sign-in works
/mcpopens the browser for OAuth. Proxy acceptslocalhostredirect URIs, which is what terminal clients use to receive the result.- There is no API key to put in a config file.
- The installer route issues a long-lived personal token instead. Use that on machines with no browser. See Personal tokens.
Large results and free cursors
Claude Code saves a very long tool result to a file instead of showing it. Proxy avoids that by sending ad lists in windows.
- A
get_meta_ads,search_meta_ads_by_keywordorget_google_adsresponse holds about 40,000 characters of ads. - If more were fetched, the response says “Showing ads 1-N of M fetched” and gives a cursor of the form
rs:<id>:<offset>. - Calling the same tool with that cursor returns the next window. It costs no credits, because those ads are already paid for.
- The stored set lasts 24 hours. After that the cursor returns an error asking to re-run the call.
Tool loading
Claude Code loads connector tools on demand. Five entry tools are loaded from the start: get_meta_platform_id, search_meta_ads_by_keyword, get_google_platform_id, search_linkedin_ads and search_tiktok_ads. The rest load when needed. If Claude Code reaches for web search, start the prompt with “Using Proxy”.
One call with a list, not parallel calls
Claude Code likes to fire several tool calls at once. For Meta, that fails: parallel single-brand get_meta_ads calls are throttled and return an error asking for one call with a list. Ask for the brands together and Proxy fetches them in one batched call.
get_google_platform_id, get_google_ad_details and get_tiktok_ad_details also accept lists, so one call covers several brands or ads.
No carousel in the terminal
The inline ad carousel needs a client that renders MCP UI. In Claude Code you get the same ads as text and JSON, with a link to each ad in its public library.
Scheduling a weekly pull
Re-running get_meta_ads or get_google_ads for the same brand with the same settings reports what changed since your last fetch: ads that are new, and how many are no longer returned. That makes a weekly job useful.
Pull Meta and Google ads for the brands in competitors.txt, write what changed to reports/ads.md, then schedule it to run weekly with /schedule.
Keep limit and filters the same between runs. The comparison is made per brand and per set of filters.
Troubleshooting
| Symptom | Fix |
|---|---|
Calls fail with an auth error after claude mcp add |
Run /mcp, sign in to proxy, restart Claude Code |
| “You called get_meta_ads N times in parallel” | Ask for all brands in one call. Proxy takes a list |
| “That cursor has expired” | The stored set is older than 24 hours. Re-run the call without a cursor |
| Output was written to a file | Lower limit, or page with the rs: cursor |
| No browser on the machine | Run the CLI installer where a browser exists and use the token it issues |
| Credits ran out mid-run | The call returns what it fetched and marks the rest as not fetched. See Credits and plans |
Example prompts
Pull the active Meta ads for [brand A], [brand B] and [brand C], 30 each, and write hooks and offers to research/meta.md.
One get_meta_ads call with three names. 6 credits.
Pull 30 Google ads for [domain] and write format, dates and ad URL of each to data/google-ads.json.
get_google_ads with limit 30.
For each company in accounts.txt, pull LinkedIn ads from the last 90 days into data/linkedin/.
One search_linkedin_ads call per company, 1 credit each.