---
title: "Ads MCP for Claude Code: setup, cursors and scheduling"
description: "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."
---

> For AI agents: the full docs index is at [https://useproxy.dev/docs/llms.txt](https://useproxy.dev/docs/llms.txt). Append `.md` to any docs URL for Markdown.

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](https://useproxy.dev/docs/meta-ads-mcp), [Google](https://useproxy.dev/docs/google-ads-mcp), [LinkedIn](https://useproxy.dev/docs/linkedin-ads-mcp) and [TikTok (EU)](https://useproxy.dev/docs/tiktok-ads-mcp).

## Connect

1. Add the server:

   ```bash
   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:

```bash
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](https://useproxy.dev/docs/authentication#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.

:::tip
Before Claude Code summarises a big pull, ask it to read every window. Otherwise conclusions cover only the first window.
:::

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

```text
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](https://useproxy.dev/docs/clients#cli-installer-any-client) 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](https://useproxy.dev/docs/credits) |

## Example prompts

```text
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.

```text
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.

```text
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

- [Meta Ads MCP for Claude](https://useproxy.dev/blog/meta-ads-mcp-for-claude)
- [How to monitor competitor ads and promotions](https://useproxy.dev/blog/how-to-monitor-competitor-ads-and-promotions)
- [Best ad library MCP servers](https://useproxy.dev/blog/best-ad-library-mcp-servers)
