Server data from the Official MCP Registry
Snapchat Ads reports, audits and safe, previewed changes to campaigns, ad squads and ads.
About
Snapchat Ads reports, audits and safe, previewed changes to campaigns, ad squads and ads.
Security Report
Valid MCP server (2 strong, 3 medium validity signals). 2 known CVEs in dependencies (0 critical, 1 high severity) Package registry verified. Imported from the Official MCP Registry.
5 files analyzed · 3 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: SNAP_ENV_FILE
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"ads-mcp-for-snapchat": {
"command": "npx",
"args": [
"-y",
"ads-mcp-for-snapchat@0.9.4"
],
"env": {
"SNAP_ENV_FILE": "your-snap-env-file-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
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.
Get started in 2 minutes
Claude Desktop (no terminal): download ads-mcp-for-snapchat-<version>.mcpb from the latest release, open it, leave Client ID and secret empty, then ask Claude: "Connect my Snapchat ad account." Log in with Snapchat and pick the ad account.
Claude Code, Cursor, VS Code or a terminal:
npx -y ads-mcp-for-snapchat setup
Choose 1. Shared login, log in with Snapchat, pick the ad account, and press Enter at the safety question (it starts read-only; nothing can be changed until you allow it). Then check everything with npx -y ads-mcp-for-snapchat verify.
What it is, and what it is not
- It runs on your machine, with your own ad account. You connect with a normal Snapchat login (the shared login service) or with your own Snapchat OAuth app. The tool itself is not hosted, and no ad account data leaves 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.
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.jsonlor<settings file>.log.jsonl) and anything you export toexports/. 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
- Goals for link ads:
snap_create_adsquadtakesgoal: purchase, add to cart, page view or sign-up (need a pixel), or traffic (SWIPES), awareness (IMPRESSIONS) and video views (no pixel needed). App installs and lead generation are not built. - Single Snap with a link (WEB_VIEW):
snap_create_creative, thensnap_create_ad. - Single Snap, no link (image or video):
snap_create_creativewithcreative_type: "SNAP_AD". - Story Ad: create the Snaps first (any of the two above), then
snap_create_story_creativewith their ids in order. Addpreview(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. - Catalog ad (Dynamic Product Ads):
snap_create_campaignwithcatalog_id(SALES objective), thensnap_create_product_set(andsnap_create_dynamic_templateif you have none), thensnap_create_adsquadwithproduct_set_idanddpa_mode(retargeting: viewed or added to cart but did not buy; prospecting: has not interacted), thensnap_create_creativewithcreative_type: "DYNAMIC_PRODUCT", thensnap_create_ad. The ad squad and the creative must use the same product set, which the tools check. The catalog and its product feed are set up in Ads Manager or Business Manager. - 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_creativewith 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.
Check that everything works on your account
npx -y ads-mcp-for-snapchat verify (or node src/cli.js verify in a git checkout; add --details to also list the specific problems it found: broken links, pixel issues, feed errors, audience problems, rejected ads) runs every read-only tool on your real account, one by one, and prints a short list: what worked, what failed and why, what was skipped (and which setting it needs). It changes nothing: it only calls tools that declare themselves read-only and forces read-only mode. The output contains no tokens and only shortened ids, so it is safe to paste into an issue.
Easiest: log in with Snapchat (no OAuth app)
Run npx -y ads-mcp-for-snapchat setup and choose 1. Shared login, or install the Claude Desktop file, leave Client ID and secret empty, and ask Claude: "Connect my Snapchat ad account." You log in with Snapchat in your browser and pick your ad account. No OAuth app to create.
How it works: a small login service (broker/, code in this repository) passes your login along and stores nothing, and your access is sealed so only your own computer can read it. Read PRIVACY.md first. The tool itself still runs only on your computer.
Status: new. It works end to end on the maintainer's real login and ad accounts, but Snap has not yet been asked to confirm that one shared app may serve other advertisers. If the login is refused for you, or you prefer not to rely on a shared service, use your own Snapchat app (next section: about 5 minutes, and setup walks you through it) or run your own copy of the service (broker/README.md).
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):
- Download
ads-mcp-for-snapchat-<version>.mcpbfrom the latest release and double-click it. Claude Desktop shows an install screen. - Enter the Client ID and Client Secret, your highest daily budget and (optional) your main country. Leave Read-only on for now.
- 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.
- 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)
git clonethis repository, thennpm ci, thennpm test(all tests are mocked and need no account).- Create a Snapchat OAuth app and connect it to your account: follow Setup (one time) below (about 10 minutes).
- Copy the safety and market settings from
.env.exampleinto.envand set your limits,SNAP_DEFAULT_COUNTRY,SNAP_ACCOUNT_CURRENCYandSNAP_REPORT_UTC_OFFSET. - Start with
SNAP_READ_ONLY=1: connect your MCP client, trysnap_ping, a report, and a few previews, and compare the numbers with Ads Manager. Remove the setting when you are comfortable. - 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-useapproval_token. To apply, the same arguments are sent again withconfirm=trueand 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 beACTIVEorPAUSED. - 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
Elicitationhook). 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)
| Setting | Default | Meaning |
|---|---|---|
SNAP_MAX_DAILY_BUDGET | 1000 | Highest daily budget any single campaign or ad squad may be given or enabled with |
SNAP_MIN_DAILY_BUDGET | 5 | Lowest daily budget |
SNAP_MAX_BID | 50 | Highest max bid |
SNAP_MAX_BUDGET_INCREASE_PCT | 100 | Largest budget increase per step and per 24 hours |
SNAP_MAX_BID_INCREASE_PCT | 50 | Largest bid increase per step and per 24 hours |
SNAP_MAX_LIFETIME_BUDGET | 30 x max daily | Highest lifetime budget a copy may carry or an enable may start |
SNAP_MAX_ACTIVATION_DAILY_BUDGET | 5 x max daily | Most daily budget one call may start (enable, undo of a pause, or a schedule change that starts delivery) |
SNAP_MAX_ADDED_DAILY_BUDGET_24H | 2 x the line above | Most daily budget this server may add to the account in any 24 hours, all tools together: budgets it starts plus budget increases |
SNAP_ACCOUNT_CURRENCY | not set | If set (e.g. USD), writes are refused unless the ad account uses that currency |
SNAP_READ_ONLY | 0 | 1 = previews and reads only |
SNAP_CAPI_TOKEN | (none) | Only for the Conversions API test tools (snap_capi_*): a Conversions API token made in Ads Manager (Events Manager > Conversions API > Generate token), used if Snap does not accept your normal login there. Sent only to tr.snapchat.com. |
SNAP_BROKER_URL | the maintainer's login service (off turns the shared login off) | The shared login service: connect with a normal Snapchat login and no OAuth app. https only. A refresh token is sent there, so use only a service you trust (see PRIVACY.md, broker/README.md). setup saves it for you. |
SNAP_HOME | ~/.ads-mcp-for-snapchat for an npm install, the project folder for a git checkout | Where the settings file, the change log and exports/ live. Set it to keep them somewhere else. |
SNAP_PORTFOLIO_FILES | (none) | Absolute paths of the settings files of the accounts for snap_portfolio_summary, comma-separated (up to 10). Only you can set it: the AI app cannot pick files. |
SNAP_TOOLSETS | all | Show only some tool groups to the AI app: setup, read, reports, checks, changes, create (comma-separated). Fewer tools make some apps faster and less error-prone, e.g. setup,reports,checks for an analyst. It only hides tools. |
SNAP_HUMAN_APPROVAL | off | elicit = ask the user through the MCP client before every write |
SNAP_APPROVAL_TTL_SECONDS | 600 | Lifetime of an approval token |
SNAP_REPEAT_WINDOW_SECONDS | 600 | An identical create, copy, claim or upload is refused within this time |
SNAP_HTTP_TIMEOUT_MS | 60000 | Deadline for each API request |
SNAP_DEFAULT_COUNTRY | not set | 2-letter country used when a tool is called without countries (new ad squads, lookalikes, targeting lookups). Not set = countries must always be given; there is no hidden default market |
SNAP_DEFAULT_PHONE_CODE | not set | Country code (digits, no +) for local phone numbers in customer lists. Not set = local numbers are counted as invalid instead of being guessed |
SNAP_REPORT_UTC_OFFSET | +00:00 | Offset for scripts/weekly-report.js and scripts/smoke.js day boundaries, e.g. +03:00 |
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.
- Budget review: checks tracking first, then suggests at most 3 budget moves with previews.
- Tracking check: pixel, yesterday's purchases, Conversions API test events, Snap vs store revenue.
- Competitor scan: a competitor's ads from Snap's public Ads Gallery (Europe), and 3 ideas.
- Fix rejected ads: why Snap rejected each ad, and a proposed fix as a preview.
- 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
| Tool | Type |
|---|---|
snap_ping | check credentials |
snap_audience_size | read: Snap's reach estimate for an ad squad or for targeting you are planning, with a verdict (very small / small / OK / very broad) |
snap_spend_pacing | read: today's spend per active ad squad vs its budget for this time of day, month-to-date spend, projected month and, with a monthly budget, over / under |
snap_ad_preview | read: a no-login preview link (90 days) and a Snapcode to scan on a phone (7 days) |
snap_list_dynamic_templates | read: the ad account's dynamic templates (product layouts for catalog ads) |
snap_create_product_set, snap_create_dynamic_template | write (preview + approval): a filtered group of catalog products; a product layout |
snap_check_landing_pages | read: opens each active ad's link once (https only, never private addresses) and flags broken, slow, server-error and non-https links, links that end on another site, and links missing parameters you name |
snap_anomaly_check | read: yesterday vs the usual day: spend spike or drop, zero or falling purchases (possible broken pixel), ROAS drop, cost-per-purchase spike |
snap_blended_roas | read: Snap's reported revenue vs the revenue your store confirms (you give the store figure): overstates, understates or consistent |
snap_audience_insights | read: who is in an audience (age, gender, languages, interests, devices) compared with everyone in the same countries, with an index |
snap_competitor_ads | read: a company's ads from Snap's public Ads Gallery (no login, nothing about your account sent; Europe only) |
snap_capi_status, snap_capi_test_event | Conversions API TEST events only: read the last test events and their errors; send one test event (previewed, email hashed). No tool sends real conversion events. |
snap_set_frequency_cap | write (preview + approval): at most N impressions per person per N hours/days, or clear it |
snap_set_ad_schedule | write (preview + approval): which hours of which days ads run; Snap allows it only on lifetime-budget ad squads |
snap_report_hourly | read: spend, purchases and ROAS by local hour of the day (last 1-7 days), best and worst hours |
snap_creative_compare | read: the ads of a campaign or ad squad ranked against the median ROAS (WINNER / LAGGING), grouped by call to action |
snap_budget_advice | read: suggested daily-budget moves (lower the weak, raise the proven, funded by what is freed, inside your limits), each naming the tool that applies it |
snap_billing_check | read: ad account status, funding sources (card expiry, daily limit vs budgets, credit left) and a verdict |
snap_unused_media | read: uploaded images and videos no creative uses (never deletes) |
snap_audience_health | read: audiences that are not targetable, tiny, stale, or unused by active ad squads |
snap_funnel | read: impressions → swipes → views → add to cart → checkout → purchases with the rate at each step and the weakest step |
snap_catalog_feed_status | read: for each catalog feed, the last completed upload, the latest upload's status and issues |
snap_set_bid_strategy | write (preview + approval): switch an ad squad between max bid and target cost with a new bid, inside the bid limits. Switching TO auto-bid is not offered (it removes the bid cap). |
snap_set_placement | write (preview + approval): automatic, or custom positions (Discover feed, Camera, Spotlight, Stories...). Undo works when a placement was set before. |
snap_portfolio_summary | read: all your ad accounts side by side (yesterday and last 7 days, what needs attention, totals per currency). Reads the settings files you list in SNAP_PORTFOLIO_FILES; the AI app cannot choose files. |
snap_connect | connect an ad account from inside the chat (link, pasted address, account choice); saves access on this computer, changes no ads |
snap_list_campaigns, snap_list_adsquads, snap_list_ads, snap_list_creatives, snap_get_entity, snap_get_media, snap_get_stats | read |
snap_report | read: ROAS, CPA, swipe rate, frequency by ad squad or ad |
snap_report_daily | read: day-by-day performance (up to 31 days) |
snap_report_audience | read: performance by country, gender, age, region, dma or make |
snap_health_check | read: audits every active squad for missing buyer exclusion, high frequency, low swipe rate, low ROAS, spend with no purchases, paused parents |
snap_review_issues | read: rejected / pending ads with Snap's reasons |
snap_pixel_health | read: pixel signal readiness and event-quality issues, top priority first |
snap_creative_fatigue | read: which ads are tired (ROAS down 30%+ with higher frequency or lower swipe rate), which to replace first |
snap_report_compare | read: two time windows side by side with the changes |
snap_report_async_start, snap_report_async_status, snap_report_async_download | read: very large CSV reports saved to exports/ |
snap_api_get | read-only GET for anything else (allow-listed paths, never writes) |
snap_list_segments, snap_list_pixels, snap_list_catalogs, snap_list_product_sets, snap_targeting_options | read: audiences, pixels, catalogs, product sets, interest/region/language ids |
snap_change_log | read the local log |
snap_set_status, snap_set_status_bulk | pause / enable (bulk up to 20, warns when a parent is paused) |
snap_set_daily_budget, snap_set_bid, snap_rename | edit |
snap_set_targeting | change countries, age, gender, interests, device OS, include segments, stop excluding segments; everything else is kept |
snap_set_schedule | set start/end time on a campaign or ad squad |
snap_exclude_segments | add buyer-exclusion audiences to an ad squad |
snap_copy_campaign | copy a campaign (all or selected ad squads, with or without ads), paused |
snap_create_campaign | create a new empty campaign, paused |
snap_create_adsquad | create a new purchase-optimized web ad squad (max bid or auto-bid, interests, device OS, buyer exclusions), paused |
snap_create_lookalike | create a lookalike audience from a customer-list seed |
snap_copy_adsquad | copy one ad squad into a campaign, paused |
snap_clone_ad | clone an ad into other ad squads, paused (skips duplicates and different product sets) |
snap_bulk_exclude_segments, snap_bulk_set_budget, snap_bulk_set_schedule, snap_bulk_rename | edit up to 20 items at once with a per-item preview; stop at the first failure |
snap_undo | revert a change from the log (refuses if the field changed again since) |
snap_clone_creative | duplicate a creative with a new name/headline/link |
snap_create_pixel_audience | audience of people who fired pixel events (e.g. ADD_CART) |
snap_upload_customer_list | customer-list audience from a local CSV; hashed locally, only hashes uploaded |
snap_influencer_batch | influencer flow for up to 10 ad codes into one squad; expired codes are skipped |
snap_delete | guarded delete: paused, no spend in 30 days, no active children, exact name typed |
snap_claim_ad_code | claim a creator ad code (one-way, single-use) |
snap_upload_media | upload a local video/image (up to 1 GB, chunked above 32 MB) to the ad account, not attached to any ad |
snap_create_creative, snap_create_ad | creative from an image or video: WEB_VIEW (swipe-up link) or SNAP_AD (the Snap only); ad from a creative, its type taken from the creative (paused) |
snap_list_media | images and videos in the account (READY by default), newest first, filter by type and name |
snap_create_story_creative | Story Ad: 1-20 existing Snaps in a fixed order, with an optional tile for the Stories tab |
snap_create_collection_creative | Collection Ad: a main image or video with 4-20 product tiles, each opening its own page |
snap_influencer_ad | the whole influencer flow in one step: claim, wait for media, creative, paused ad |
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 toexports/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 ad account, and (for now) their own OAuth app. Nothing about your ad account is hosted or shared; the optional login service (see above) only handles the Snapchat login.
Setup (one time)
- In Snap Ads Manager open Business Details > OAuth Apps and create an app. Redirect URL must be https and not
localhost, for examplehttps://127.0.0.1/callback. The client secret is shown once: select it and copy it before leaving the page. - Copy
.env.exampleto.env, fill inSNAP_CLIENT_IDandSNAP_REDIRECT_URI. - Save the secret from your clipboard:
node scripts/save-secret.js(reads the clipboard on macOS, Windows, and Linux withwl-paste,xcliporxsel; it refuses text that does not look like a secret and clears the clipboard). Without a clipboard tool usenode scripts/save-secret.js --stdin, or addSNAP_CLIENT_SECRET=...to.envyourself and make the file private (chmod 600 .env). - 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 - The browser redirects to
...?code=.... Within a minute or two run:CODE=THE_CODE node scripts/get-refresh-token.js. It savesSNAP_REFRESH_TOKENinto.envand prints nothing secret. node scripts/check.jsrefreshes the token and tests/meand the ad account (read-only).- 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.
- Copy your settings:
cp .env .env.account2. In.env.account2, set that account'sSNAP_AD_ACCOUNT_ID,SNAP_PIXEL_ID,SNAP_BRAND_PROFILE_IDand its own limits. Every.env*file except.env.exampleis git-ignored. - 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, thenSNAP_ENV_FILE=.env.account2 node scripts/check.js. If the same login can see both accounts, the copied credentials already work. - 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(-etakes every value after it).-e SNAP_READ_ONLY=1starts 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. - Restart, then check that
snap_pingshows the new account's id (not the first account's) andreadOnly: 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_undopreview and undo. - Story Ads (0.3.0): a Story creative from two existing creatives (account and type checks, fixed order), then
snap_create_adchoosing 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_adchoosing 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).
Read-only run of verify on the maintainer's real ad account (November 2026, 23 of 24 tools worked; and 20 of 24 with none failed on a second account connected through the shared login, the rest skipped for optional settings): snap_ping; the campaign, ad squad, media and audience lists; spend pacing; anomaly check; funnel; hourly report; billing check; audience health; unused media; budget advice; landing page check; health check; review issues; dynamic template list; catalog feed status; pixel health; audience size; audience insights; and the public Ads Gallery lookup. That run found real bugs that mocked tests could not (Snap's account-level stats accept only the spend field; the landing page check read too much; a shop's bot protection answered 403), all fixed in 0.9.1 and after.
Not verified live:
- Everything that writes and was added in 0.7.0 or later: catalog ad creation (product sets, templates, campaign, ad squad, creative, ad), frequency cap, ad schedule, placement, bid-strategy switching, and the new ad squad goals. Built from Snap's documentation and mocked tests.
- The Conversions API test tools (they need a Conversions API token:
SNAP_CAPI_TOKEN), the portfolio summary (needs a second settings file), blended ROAS (needs your store's revenue), creative comparison, ad preview, and the playbooks. - The shared login for people outside the maintainer's organization, and the Claude Desktop extension's login. (Setup's shared login, the account list and renewing the login through the service were run live on the maintainer's account.)
- The 24-hour spend limit and absolute limits on real writes (mocked tests only),
SNAP_HUMAN_APPROVAL=elicitin Claude Code,snap_create_creativewith a WEB_VIEW link, a campaign-levelsnap_set_daily_budget, a successfulsnap_deleteof 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 MCP server, which ChatGPT would need. The optional shared login service (
broker/) only passes Snapchat logins along; the tool itself always runs on your own computer. - Lens, App Install, Deep Link and lead-form creatives; ad squad goals for app installs and lead generation; custom location and radius targeting; reach-and-frequency budgets; position-level reports; custom placement on ad squads that use content inclusion or exclusion lists; switching an ad squad to auto-bid (it would remove the bid cap).
- 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.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
