For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  1. Add the server:

    claude mcp add --transport http proxy 'https://mcp.useproxy.dev/mcp?ref=docs'
  2. Run /mcp inside Claude Code and sign in to proxy.

  3. Restart Claude Code.

  4. 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

  • /mcp opens the browser for OAuth. Proxy accepts localhost redirect 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_keyword or get_google_ads response 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.

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.

Guides

Was this page helpful?