Ads MCP for Snapchat

A local MCP server that lets an AI assistant (Claude Code, Claude Desktop and other MCP clients) work with your own Snapchat ad account: read performance, audit campaigns, and make careful, reviewable changes. It also turns creators' ad codes into paused ads.

Unofficial. Not affiliated with or endorsed by Snap Inc. This tool can change real ad campaigns that spend real money. You use it at your own risk (see LICENSE). Check Snap's developer terms for your own use. Review every preview before approving.

What it is, and what it is not

• It runs on your machine, with your own Snapchat OAuth app and your own ad account. Nothing is hosted or shared, and no credentials leave your computer except to Snap's API.

• It is a safety-first tool, not an autopilot. Writes are previewed first, created things start paused, and there are hard limits on money. See "Safety rules" below, and read "What the approval token is not".

• It is not a hosted service. Services that only accept remote MCP servers (for example ChatGPT connectors) cannot use it as it is. Do not expose it on the internet.

• Money limits are in your account's currency. Defaults (SNAP_MAX_DAILY_BUDGET=1000, SNAP_MAX_BID=50) are deliberately conservative; set your own in .env.

Related MCP server: mcp-openai-ads

Snap's terms and data

• This project is not Snap's official Ads MCP server and is not endorsed by Snap Inc. "Snapchat" is a trademark of Snap Inc.; it is used here only to say which API this tool works with.

• Using the Snapchat Marketing API means accepting Snap's Developer Terms and Business Tools Terms. Read them yourself; they include duties on how long Snap data may be kept and how it must be protected.

• This server keeps data only on your machine: the change log (changes.log.jsonl or <settings file>.log.jsonl) and anything you export to exports/. You are responsible for keeping and deleting those files in line with Snap's terms.

• Data that comes back from the API (names, review reasons) is shown to your AI assistant. Treat it as untrusted input, and keep your client's approval prompt on for write tools.

Ad formats

• Single Snap with a link (WEB_VIEW): snap_create_creative, then snap_create_ad.

• Single Snap, no link (image or video): snap_create_creative with creative_type: "SNAP_AD".

• Story Ad: create the Snaps first (any of the two above), then snap_create_story_creative with their ids in order. Add preview (a 3:5 PNG tile, at least 360x600 px, and a headline of up to 55 characters) to also show it in the Stories tab.

• Collection Ad: upload a main image or video and one square image per product (1:1, at least 120x120 px; checked in the preview), then snap_create_collection_creative with 4-20 products, each with its own https page.

In every case snap_create_ad picks the matching ad type (REMOTE_WEBPAGE, SNAP_AD, STORY or COLLECTION) and the ad starts PAUSED. Creatives never deliver on their own. Find media already in the account with snap_list_media, or upload with snap_upload_media and wait until snap_get_media says READY.

Easy setup (about 5 minutes)

First, once: in Snap Business Manager open Business Details > OAuth Apps > + OAuth App, use the Redirect URI https://127.0.0.1/callback, and copy the Client ID and Client Secret (the secret is shown only once).

Claude Desktop (no terminal):

1. Download ads-mcp-for-snapchat-<version>.mcpb from the latest release and double-click it. Claude Desktop shows an install screen.

2. Enter the Client ID and Client Secret, your highest daily budget and (optional) your main country. Leave Read-only on for now.

3. In a chat, ask: "Connect my Snapchat ad account." Claude gives you a link; approve in the browser, paste back the address it lands on, and pick your ad account from the list.

4. Quit and reopen Claude Desktop. Ask: "call snap_ping".

Claude Code, Cursor, VS Code (one command, needs Node 18+):

npx -y ads-mcp-for-snapchat setup

It asks for the Client ID and secret (hidden), opens the approval page, lists your ad accounts to choose from, asks for your first safety settings, and adds the server to Claude Code. For Cursor, VS Code or Claude Desktop it prints the exact settings to paste. Another ad account: npx -y ads-mcp-for-snapchat setup --file ~/.ads-mcp-for-snapchat/.env.account2.

Settings, the change log and exports live in ~/.ads-mcp-for-snapchat/, outside the package, so updates never touch them. npx -y ads-mcp-for-snapchat help lists the other commands (check, where, weekly-report, and the step-by-step init, save-secret, auth). It is also listed in the official MCP Registry as io.github.Usame794/ads-mcp-for-snapchat.

Quick start (from source)

1. git clone this repository, then npm ci, then npm test (all tests are mocked and need no account).

2. Create a Snapchat OAuth app and connect it to your account: follow Setup (one time) below (about 10 minutes).

3. Copy the safety and market settings from .env.example into .env and set your limits, SNAP_DEFAULT_COUNTRY, SNAP_ACCOUNT_CURRENCY and SNAP_REPORT_UTC_OFFSET.

4. Start with SNAP_READ_ONLY=1: connect your MCP client, try snap_ping, a report, and a few previews, and compare the numbers with Ads Manager. Remove the setting when you are comfortable.

5. Keep your client's permission prompt on for write tools.

Safety rules (built in)

• Every write tool works in two steps. confirm=false (the default) returns a preview and a single-use approval_token. To apply, the same arguments are sent again with confirm=true and that token. The token is bound to the tool, the ad account, the arguments and the state of the items at preview time: if anything changed, or the token is reused, expired or from another request, nothing is sent.

• Everything that creates something (copies, clones, new ads, new creatives) is created PAUSED. Enabling is a separate step, and its preview shows the daily budget that would really start delivering (for a campaign: the budgets of its ACTIVE ad squads).

• Absolute limits, in account currency, apply to every path that can raise money (set, bulk, create, copy, undo, enable): see the table below. On top of them, a budget may rise at most +100% and a bid +50% per step and per 24 hours (counted from this server's change log), so repeating a step does not compound.

• Writes only touch items of the configured SNAP_AD_ACCOUNT_ID. Ids are validated before they are used.

• The only delete tool is snap_delete, behind many guards. Status can only be ACTIVE or PAUSED.

• Every write is recorded in changes.log.jsonl: an intent record before anything is sent (if it cannot be written, the operation does not run) and a result record after, with tool, account, target ids, redacted arguments, and before/after values for edits. Credentials are never logged; ad codes are masked.

• Multi-step creates (copy, influencer flow) stop at the first failure and report exactly what was already created. A write that fails in transit is never re-sent; it is reported as "outcome unknown".

• Safety settings are validated when the server starts. An invalid value (for example 100%) stops the server instead of switching the limit off. Limits and the target account are fixed until restart; only the OAuth credentials are re-read from .env.

What the approval token is not

The token proves that this exact change was previewed and that nothing moved since. It does not prove that a person looked at it: the AI client receives the token and can send it back by itself. Human authorization is the permission prompt of your MCP client, so do not auto-approve the write tools. Tools are annotated (readOnlyHint, destructiveHint) so a client can auto-allow reads only. SNAP_READ_ONLY=1 turns every write off.

Asking you directly (SNAP_HUMAN_APPROVAL=elicit)

With this setting the server asks you, through the MCP client's own dialog (MCP elicitation), before every write, and refuses when it cannot ask. The question and your answer do not pass through the model. For anything that adds spend, for deletes and for undo, you must also type a 4-digit code that only the dialog shows. Limits you should know:

• It needs a client that shows elicitation dialogs. Claude Code documents this for interactive terminal sessions; in non-interactive sessions the request is cancelled, so writes are refused. This server's tests use the SDK's client, not Claude Code itself: try one harmless write (a rename) before relying on it.

• A client can be configured to answer elicitations automatically (in Claude Code, an Elicitation hook). Such a hook removes the human from the loop. Do not install one for this server, and keep your client's settings files out of reach of the AI's file tools.

Safety settings (.env, all optional, restart to apply)

Reports state what their numbers mean (basis): amounts are Snap micro-currency divided by 1,000,000 in the account currency, purchases are Snap-attributed, and attribution uses the account's default windows unless you pin them with swipe_up_attribution_window / view_attribution_window on snap_report and snap_report_daily. Totals are computed from raw values (account ROAS = purchase value / spend). A report that was cut off says incomplete or truncated.

Existing items above a limit can still be read, lowered and paused, but not raised or enabled until the owner raises the limit. The 24-hour rules and the audit trail rely on changes.log.jsonl (plus an in-memory copy while the server runs, so deleting the file does not reset them until a restart); changes made in Ads Manager are not counted, and the file is not tamper-proof against someone with access to your disk. Keep .env and the log out of reach of the AI client's file tools (for Claude Code: a Read/Edit deny rule for the project folder).

Playbooks

Ready-made instructions in Claude's prompt menu (the "+" or "/" menu). They only read and preview; nothing is applied without your yes.

• Weekly review: last 7 days vs the 7 before, problems, tired ads, pacing, and up to 5 actions.

• Launch checklist: before turning on a paused campaign or ad squad: audience size, pixel, budget, creatives, review status, preview links. PASS / WARN / FAIL per item.

• Replace tired ads: finds wearing-out ads in a campaign and drafts paused replacements from new media.

Tools

Influencer ad-code flow

Creators share a code like adcode_<uuid>. snap_influencer_ad claims it into the ad account (POST /adaccounts/{id}/claim_media_by_ad_code?ad_code=&profile_id=, parameters go in the query string), waits for the media to be READY, creates a WEB_VIEW creative on the brand profile (SNAP_BRAND_PROFILE_ID) and creates a paused ad in the ad squad you choose. Notes from live use:

• Claiming is one-way and codes are single-use. Expired codes return "Ad code has expired" and are not consumed.

• Codes beyond their lifetime cannot be refreshed; ask the creator for a new one.

• Codes starting with # are for other platforms and are rejected.

Scripts

From an npm install, use npx -y ads-mcp-for-snapchat check | weekly-report instead; reports then go to ~/.ads-mcp-for-snapchat/exports/.

• npm run smoke: live read-only check of credentials, token refresh and the main read paths (exit code 1 on any failure). Run it after changing a secret or updating the server.

• npm run weekly-report: read-only weekly report saved to exports/weekly-<date>.md (spend and ROAS vs last week, top campaigns, account health, tired ads, review problems, pixel issues). Optional argument: end date, e.g. npm run weekly-report -- 2026-10-27.

• Reliability: reads retry automatically on rate limits (429), server errors and network errors; writes retry only on 429, so a create or claim is never repeated by accident.

Requirements

Node 18+ and a Snapchat Ads account with permission to create an OAuth app. Install dependencies with npm install. Run the tests with npm test (all mocked, no credentials needed).

Each user runs this server locally with their own OAuth app and their own ad account. Nothing is shared or hosted.

Setup (one time)

1. In Snap Ads Manager open Business Details > OAuth Apps and create an app. Redirect URL must be https and not localhost, for example https://127.0.0.1/callback. The client secret is shown once: select it and copy it before leaving the page.

2. Copy .env.example to .env, fill in SNAP_CLIENT_ID and SNAP_REDIRECT_URI.

3. Save the secret from your clipboard: node scripts/save-secret.js (reads the clipboard on macOS, Windows, and Linux with wl-paste, xclip or xsel; it refuses text that does not look like a secret and clears the clipboard). Without a clipboard tool use node scripts/save-secret.js --stdin, or add SNAP_CLIENT_SECRET=... to .env yourself and make the file private (chmod 600 .env).

4. Open this URL in a browser signed in to Snapchat and approve (replace the two values): https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=snapchat-marketing-api&state=ads-mcp-for-snapchat

5. The browser redirects to ...?code=.... Within a minute or two run: CODE=THE_CODE node scripts/get-refresh-token.js. It saves SNAP_REFRESH_TOKEN into .env and prints nothing secret.

6. node scripts/check.js refreshes the token and tests /me and the ad account (read-only).

7. Register: claude mcp add --scope user snapchat-ads -- node "/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat/src/index.js", then restart Claude Code.

Use it from Claude or ChatGPT

This is a local MCP server (stdio). Credentials stay in your .env; the AI app only starts the process.

Claude Code (step 7 above): claude mcp add --scope user snapchat-ads -- node "/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat/src/index.js", then restart. Check with claude mcp list.

Claude Desktop: open Settings > Developer > Edit Config and add this to claude_desktop_config.json, then fully quit and reopen the app:

{
  "mcpServers": {
    "snapchat-ads": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat/src/index.js"]
    }
  }
}

Use the absolute path to node as command if the app cannot find it. The server reads .env from its own folder (an npm install reads ~/.ads-mcp-for-snapchat/.env), so no secrets go in this file.

ChatGPT: ChatGPT connects to remote MCP servers (an https URL) through its connectors / developer mode, not to local stdio programs. This server is local only, so it cannot be added to ChatGPT as it is. Doing that would need a hosted version with per-user OAuth and encrypted token storage (see "Not built"). Do not expose this server publicly as it is: it can change real ad campaigns. Other desktop MCP clients that launch local stdio servers (Cursor, VS Code, Cline) work with the same command and args as above.

Several ad accounts

Run one server per ad account, each with its own settings file. Each server only touches its own account, and keeps its own change log (<settings file>.log.jsonl), so limits, undo and the audit trail never mix.

1. Copy your settings: cp .env .env.account2. In .env.account2, set that account's SNAP_AD_ACCOUNT_ID, SNAP_PIXEL_ID, SNAP_BRAND_PROFILE_ID and its own limits. Every .env* file except .env.example is git-ignored.

2. If that account belongs to another Snapchat login, authorize it into its own file (same steps as "Setup", with the variable in front): SNAP_ENV_FILE=.env.account2 node scripts/get-refresh-token.js, then SNAP_ENV_FILE=.env.account2 node scripts/check.js. If the same login can see both accounts, the copied credentials already work.

3. Register a second server with an absolute path to the file: claude mcp add --scope user snapchat-ads-2 -e SNAP_ENV_FILE="/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat/.env.account2" -e SNAP_READ_ONLY=1 -- node "/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat/src/index.js" The server name must come before -e (-e takes every value after it). -e SNAP_READ_ONLY=1 starts the new account read-only, whatever its file says; remove it (claude mcp remove snapchat-ads-2, then add it again without it) when you are ready.

4. Restart, then check that snap_ping shows the new account's id (not the first account's) and readOnly: true.

Scripts work the same way: put SNAP_ENV_FILE=.env.account2 in front of any node scripts/... command.

Weekly report on a schedule

npm run weekly-report writes exports/weekly-<account>-<date>.md (read-only; nothing is changed in the account). To run it every Sunday at 09:30 on macOS or Linux, add a line with crontab -e, using the full path of node (which node):

30 9 * * 0 cd "/ABSOLUTE/PATH/TO/ads-mcp-for-snapchat" && /full/path/to/node scripts/weekly-report.js >> "$HOME/snap-weekly.log" 2>&1

The computer must be awake at that time. Set SNAP_REPORT_UTC_OFFSET so the week starts at your local midnight. For a second account add SNAP_ENV_FILE=.env.account2 before /full/path/to/node.

Verified live (against the real Snapchat API)

Verified on the maintainer's own ad account. Anything not listed here is covered by mocked tests only: try it with SNAP_READ_ONLY=1 on your account first.

After the safety layer (November 2026):

• Connection and settings: token refresh, snap_ping (shows the limits in force), start-up validation of .env.

• Reads: campaign and ad squad lists across more than one page, finding one campaign among about 2,000 with name_contains, ad squad details.

• Reports: the weekly report's account spend for a full week matched the figure in Ads Manager for the same dates and time zone. Purchases and ROAS use Snap's attribution and can differ from other tools.

• Previews: enabling a campaign and an ad squad shows what would really start delivering, including an ad squad under a paused campaign, and its daily budget matched Ads Manager.

• One real write on a throwaway campaign: preview, approval token, rename, read-back verification, audit entries (intent and result), snap_undo preview and undo.

• Story Ads (0.3.0): a Story creative from two existing creatives (account and type checks, fixed order), then snap_create_ad choosing ad type STORY, created PAUSED in a paused test ad squad.

• SNAP_AD creative (0.3.0): a Snap with no link from an uploaded vertical video.

• Collection Ads (0.3.1): 4 product tiles, the product row, the COLLECTION creative, then snap_create_ad choosing ad type COLLECTION, created PAUSED in a paused test ad squad. Snap refused non-square product images, which the preview now checks (0.3.2).

Before the safety layer (earlier tests, on throwaway paused objects): pause/enable (single and bulk), budget, bid, targeting, schedule, bulk edits, campaign / ad squad copy, ad and creative clone, create campaign and ad squad, lookalike and pixel audiences, customer-list audience (with fake data), influencer flow and batch, media upload (simple and chunked), async reports, health check, review issues, pixel health, and the guarded delete (on a throwaway campaign).

Not verified live: snap_audience_size, snap_spend_pacing and snap_ad_preview (0.6.0, built from Snap's documentation and mocked tests), the 24-hour spend limit and absolute limits on real writes (mocked tests only), SNAP_HUMAN_APPROVAL=elicit in Claude Code, snap_create_creative with a WEB_VIEW link, a campaign-level snap_set_daily_budget, a successful snap_delete of an ad squad, ad or audience, a customer-list upload of real data, and Node 18 / 20 outside CI.

Not built

• A hosted multi-user version (this server runs on your own machine with your own credentials).

• Lens, App Install, Deep Link, lead-form and dynamic product creatives, product set creation, ad squad types other than purchase-optimized web squads, custom location/radius targeting, lifetime or reach-and-frequency budgets, and position-level reports.

• Anything that spends money without a separate, explicit enable step.

Development

npm ci, then npm test (all tests use a mocked API; none touch your account). See ARCHITECTURE.md for the design and CONTRIBUTING.md before sending changes.