MCP Configuration

MCP (Model Context Protocol) is a standard way for AI apps to use outside tools. The Ads Uploader MCP server gives your AI agent the same surface the CLI uses: browsing accounts, campaigns, ad sets and ads, uploading media, saving presets, working with saved builds, previewing a build and creating ads. If you know the web app or the CLI, the MCP tools follow exactly the same workflow.

MCP access is for paid plans and is not available during a trial. It uses the same account and Meta connection as the web app and CLI, and it is switched off whenever CLI access is switched off for an account.

CLI or MCP?

Both run on the same infrastructure, so this is a choice of workflow, not of features. The CLI is the better fit when you want to run your whole operation through an AI agent: bulk uploads from disk, repeated launches, and complete builds assembled from the terminal.

The MCP is better for targeted jobs where the web app stays in the loop. For example:

Upload and check all your media in the web uploader, then hand the build to the agent for one step
Have the agent set up the ad set configuration
Have the agent write or rewrite your ad text
Match ad copy from a spreadsheet to the file names of your uploads

Saved builds connect the two. The web uploader, CLI and MCP all use the same build references, so a build can pass back and forth without anyone typing it in again. See Saved Builds.

Connect a Chat App (Claude, ChatGPT, Cursor)

Use the hosted server when you work from a chat app and want to sign in through your browser. Add this URL as a custom connector in your app:

https://adsuploader.com/api/mcp

For example, in Claude go to Settings > Connectors > Add custom connector. ChatGPT and Cursor also support custom MCP connectors. After you add it, finish the Ads Uploader sign-in and consent screen in your browser. There is no token to copy or paste. To check it works, ask your agent to list your ad accounts.

Connect a Coding Agent (Claude Code, Claude Desktop, Cursor)

Coding agents can use the same hosted server. In Claude Code, run:

claude mcp add --transport http ads-uploader https://adsuploader.com/api/mcp

In other agents, add https://adsuploader.com/api/mcp as a remote MCP server and complete the browser sign-in when asked. If your agent only supports local (stdio) servers, bridge to the hosted server with npx mcp-remote https://adsuploader.com/api/mcp.

Run the Server on Your Own Computer

You can also run the MCP server locally. This is useful when you want the agent to upload files straight from your disk. It needs Node.js 18 or later:

npm install -g @adsuploader/cli @adsuploader/mcp
ads login

Then add the ads-mcp command to your agent's MCP settings:

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

The local server uses the login saved by ads login. It does not open a browser itself, so run ads login again when that login expires (after 30 days).

What Your Agent Can Do

The server gives your agent tools for the full build workflow. You describe what you want in plain language, and the agent calls the tools for you.

Area	What the agent can do
Identity	Confirm which Ads Uploader user it is signed in as before it changes anything
Accounts	List your Meta ad accounts and pass the right `accountId` to each call
Browsing	List campaigns, ad sets, ads and Pages; read an ad's full creative settings
Targeting	Look up city keys, zip codes and detailed targeting IDs with `ads_search_targeting`, so it never has to guess them
Presets	List saved API and ad text presets, read one preset with `ads_get_preset`, and save an existing ad as a preset
Builds	List, read, save, update and delete saved builds, or copy one into a new draft with `ads_fork_build` so the original stays as it is. Every build comes with a link that opens it in the web uploader.
Media	Upload images and videos to your ad account and list recent upload batches
Preview	Show exactly what would be created before anything is made
Create	Create ads from a preset, a copied ad, a saved build or a full spec, then track or cancel the job
Duplicate by post ID	Preview a post-ID duplication with `ads_duplicate_by_post_preview`, start it with `ads_duplicate_by_post`, and follow it with `ads_get_duplication`

Preview first. On the hosted server, ads_create watches the job for about 60 seconds. If the job is still running, it returns the job reference and your agent keeps checking it with ads_get_job. The job itself runs on the server and does not depend on the connection staying open. On the local server, ads_create can watch for up to 30 minutes.

Work with Saved Builds

Builds autosave as you work in the web uploader. Each one has a lasting reference (build_...), shown at the bottom of the configuration step and in the Saved Builds window. Give that reference to your agent and it can read the exact configuration you see, change it, and save it back to the same build.

If the build is open in the uploader, the uploader picks up the saved change and applies it for you when you have no unsaved edits. You can also click the refresh button next to the build reference to check straight away. If you have unsaved edits when an outside change arrives, the uploader asks whether to load the outside changes or keep yours, so neither version is lost. If the tab is closed, ask the agent for the build link.

The per-ad and per-ad-set text editors in the web uploader have Claude and ChatGPT buttons that open a chat with your build reference already filled in, so handing over a text pass takes one click. It also works the other way: ask the agent to save its work as a build, then open the link to check everything in the browser before any ads are created.

Upload Media

How files reach your ad account depends on where the server runs:

Hosted server (chat apps and coding agents using the hosted URL): give the agent public HTTPS download links, a public Google Drive file link, or one public Drive folder link. Ads Uploader downloads and processes the files in the background, so the file data never passes through the chat.
Local server (ads-mcp): the agent can also upload files straight from your disk. You can also use the CLI with ads upload for folders on your computer.

After a link or Drive upload starts, the agent checks it with ads_get_upload. When it finishes, the result includes the batch summary used for previews and ad creation. To stop an unwanted import, the agent calls ads_cancel_job; files that already finished stay usable, and the result shows how many completed, failed or were skipped. Images named *_thumbnail are attached to their matching video as custom thumbnails instead of being counted as separate media, so a folder's media total can be lower than its file count. If Google blocks a folder import for a while, the result says what completed, failed and was skipped, so the agent can tell you to try again later.

Drive links must be shared as Anyone with the link (Viewer). Private Drive files are a web uploader feature.

Small images can also be sent inline (up to 10 MB in total per call). A coding agent that can send file data itself can ask for the older direct upload path, which uploads to Ads Uploader storage. Only that path needs outbound access to our upload host. If your agent runs in a network sandbox, allow *.adsuploader.com in your agent's network or sandbox allowlist. The upload response names the exact host in allowlistHost; if it ever differs, trust the response.

Limits

50 files per upload call. Split bigger uploads into several calls.
Rate limits. Calls are limited per user and per kind of call over a rolling minute (for example, 120 MCP tool calls a minute, and 20 a minute for each kind of list or preview call). Normal use stays well below these. If your agent hits a limit, it gets a "rate limit" error and should wait before trying again.
One ad creation job at a time per user, the same as the CLI.

The hosted server signs you in with OAuth, the standard "sign in and approve" flow. The access token it issues lasts one hour. If your app supports refresh tokens, it also gets a refresh token that lasts 30 days and uses it to renew the access token in the background, so you do not have to sign in every session. Otherwise, the app asks you to sign in again when the token runs out.

Access follows your account: it is for paid plans only, and switching off CLI access for an account also removes its MCP access straight away.

Partnership Ads

The MCP ads_preview and ads_create tools accept the same partnership specs as the CLI:

With your own media: add profile.partnership.enabled: true with your partner's IDs to a normal media spec. You can set a different partner per ad or per ad set.
From existing Instagram posts: import an authorized post with mediaItems[].kind: "partnershipPost".

Preview shows each ad's partner, approval and header mode, grouped by ad set. For the full spec shapes and limits, see Partnership ads with your own media and Instagram existing-post partnership spec.

Documentation