Connect Ads Uploader to MCP hosts such as Claude.ai, ChatGPT, Claude Code, Claude Desktop, and Cursor. The hosted server and local stdio package expose the CLI's API surface.

Setup

Option A: Hosted server (recommended)

Add this URL as a custom MCP connector in Claude.ai, ChatGPT, or Cursor, then complete the sign-in and consent screen in your browser:

https://adsuploader.com/api/mcp

In Claude Code, run:

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

For hosts that only support stdio, bridge to the hosted server with:

npx mcp-remote https://adsuploader.com/api/mcp

The hosted server authenticates through OAuth in your browser. No CLI login or token copying is needed. Ask the agent to list your ad accounts to check the connection.

Option B: Local stdio package

Requires Node.js 18 or later. Install both packages and authenticate once in your terminal:

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

Configure your MCP host with:

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

The local server reads ~/.config/adsuploader/credentials.json saved by ads login. It does not open a browser or run OAuth itself. Use local stdio when the agent needs to upload files from disk with paths.

Tools

The server exposes tools for accounts, campaigns, ad sets, ads, pages, presets, uploads, saved builds, previews, ad creation jobs, post-ID duplication jobs, and cancellation. ads_create watches for up to 30 minutes on local stdio. The hosted route returns still_running with a jobId after about 60 seconds so the HTTP tool call stays below proxy deadlines; resume with ads_get_job.

ads_create and ads_preview accept the full v1 AdSpec request body: media source (uploadId / mediaItems / buildId), copyFromAd, adPresetId, textPresetId, campaign structure, adSet structure with dailyBudget/bidAmount/minimumRoas, targeting (locations, age, gender, detailed targeting), profile Page/Instagram/Threads overrides, texts (common / per ad / per ad set, plus landing-page urlVariants), cta, carousel, flexible, multimedia, creativeEnhancements, aiDisclosure (Meta AI-content self-disclosure, off by default and never auto-enabled), adNamePattern, and options (status, pauseAt, schedule).

ads_duplicate_by_post and ads_duplicate_by_post_preview accept ordered exact adIds or postIds for discovery, never both. Preview returns sourceCandidates and a pinned resolvedRequest; ambiguous matches require an explicit choice and no objects are created. Submit resolvedRequest plus accountId to retain a reviewed selection. Live calls preview first and submit only exact ad IDs. Warned runs require acknowledgeWarnings: true or an explicit useCreativeId: true. Only existing campaigns are supported, with existing/shared/per-ad ad sets. Use ads_get_duplication to resume still_running jobs.

See SKILL.md for the full per-parameter reference (types, defaults, and examples) that MCP agents should follow.

For hosted media uploads, pass public HTTPS source URLs in files[].url, a public Google Drive folder in driveFolderUrl, or paste a public Drive file link as a URL. Ads Uploader runs bounded parallel download, staging, and processing pipelines in one background job. Poll ads_get_upload with the returned jobId; its progress.files reports every active file and its result contains the final batch summary when complete is true. Cancel an unwanted import with ads_cancel_job and the ingest jobId. A Google access block is reported as result.blocked with completed, failed, and skipped counts. The summary's thumbnailsAttached counts *_thumbnail images attached to their videos as custom thumbnails, so total can be lower than the submitted file count. Filenames for URL sources always come from the remote source; name applies only to base64 and presigned files.

Inline base64 is limited to a couple of small images. presigned:true remains available only to environments that can PUT file bytes themselves, and hosted ads_upload_finalize also returns a background ingest job. Local stdio hosts can still use paths for files on disk.

Hosted authentication reference

The hosted server at https://adsuploader.com/api/mcp speaks Streamable HTTP JSON-RPC and is protected by OAuth 2.1.

Remote MCP clients discover the OAuth metadata from:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server

The authorization flow is:

Register the MCP client with RFC 7591 Dynamic Client Registration at /api/oauth/register.
Send the user to /api/oauth/authorize. The route reuses the user's NextAuth session when present, shows consent, and requires PKCE S256.
Exchange the authorization code at /api/oauth/token. The token endpoint issues an Ads Uploader token with source=mcp.

Local development

The remote route uses MCP_API_BASE_URL for its server-to-server calls to /api/v1. When this variable is not set, the route defaults to the request issuer. For local development, https://localhost:3001 usually uses a self-signed certificate, so set MCP_API_BASE_URL to an internal origin the server can reach without TLS verification failure, such as the non-HTTPS local app origin that is serving the same preview.