Snapchat Ads

影片展示的是使用示例数据的托管版 getmcpads。从创意素材库和提醒，到 Google Sheets 导出和批量发布，其 MCP Apps 均属于托管产品。本仓库提供独立的原生 API 工具。

21 个读取工具 · 25 个写入工具，默认禁用。

使用你自己的 Snap Marketing API 凭据，以及支持 stdio MCP 的客户端（例如 Claude Desktop、Claude Code 或 Cursor）在本地运行。你的请求会直接发送至 Snap。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管版。

更新内容

v1.0.0：首个独立版本 · 2026 年 10 月 23 日

• 首个独立服务，移植自 getmcpads 网关的修订版本 3e1c2c8：包含 21 个原生读取工具、25 个原生写入工具，以及 snapchat://guide 和 snapchat://reporting-fields 资源。
• 要求设置 SNAPCHAT_ADS_ACCOUNT_IDS，并针对所选广告账户检查每个请求和每个引用的实体。
• 除非 SNAPCHAT_ADS_ENABLE_WRITES 的值严格为 true，否则禁用写入。每项写入操作都会先预览，直到设置 confirm: true；广告系列、广告组和广告均以暂停状态创建。
• 在内存中使用刷新凭据续期访问令牌，不将其写入任何位置，并从所有错误信息中删除凭据。
• 仅访问 adsapi.snapchat.com 和 accounts.snapchat.com，不跟随重定向，并设置超时和 16 MB 的响应大小上限。
• 将 HTTP 200 响应中请求失败或部分条目失败的情况报告为错误；明确报告单项创建被拒绝且未应用。
• 不包含托管版的冻结文件上传、创意素材库 UI、提醒和 Launcher。
• 要求使用 Node.js 22.23.4、24.22.1、26.12.1 或相应版本线中的更新版本；否则在 stderr 上发出警告，并在 CI 中测试 Node 22、24 和 26。

完整更新日志 · 所有版本

源码同步：SOURCE_SYNC.md。

升级说明

要求使用 Node.js 22.23.4、24.22.1、26.12.1 或这些版本线中的更新版本。这些版本包含 2026 年 10 月的安全修复；在较旧版本上运行时，服务会在 stderr 上输出警告。CI 覆盖 Node 22、24 和 26。写入功能仍为可选，且必须明确确认。托管版创意集成和 MCP Apps UI 不属于此版本。

安装此版本

这是 GitHub 源代码发行版。npm 和 MCP Registry 版本会单独发布。下面的命令会选择此确切版本；本文后面的未锁定版本 npx 示例会选择 npm 上当前可用的版本。

git clone --branch v1.0.0 --depth 1 https://github.com/get-mcp-ads/snapchat-ads-mcp-server.git
cd snapchat-ads-mcp-server
npm ci
npm run build

配置 MCP 客户端，使用 node 运行 dist/cli.js 的绝对路径，并设置下文所述的环境变量。

托管连接。 通过托管版 getmcpads 使用 Snapchat Ads。连接你的账户，选择助手可以访问的数据，然后使用托管的 MCP 连接。当前功能和方案请参阅网站。

配置

通过客户端的机密配置提供以下环境变量：

变量	用途
SNAPCHAT_ADS_ACCOUNT_IDS	必填。此服务可使用的广告账户 UUID，多个 ID 以逗号分隔。对于任何其他账户的请求，都会在离开你的计算机前被拒绝。组织 ID 并非广告账户 ID。
SNAPCHAT_ADS_REFRESH_TOKEN	你自己的 Snap Marketing API OAuth 应用的刷新令牌。与下方两个变量一起使用时，服务会在内存中续期访问令牌。
SNAPCHAT_ADS_CLIENT_ID	该 OAuth 应用的客户端 ID。
SNAPCHAT_ADS_CLIENT_SECRET	该 OAuth 应用的客户端密钥。
SNAPCHAT_ADS_ACCESS_TOKEN	可选访问令牌。单独使用时，令牌会在一小时后由 Snap 过期。与刷新凭据一起使用时，会优先使用该令牌。
SNAPCHAT_ADS_ENABLE_WRITES	默认为 false。只有值恰好为 true 时才会启用写入工具。任何其他值都会导致服务在启动时停止。

请设置 SNAPCHAT_ADS_ACCESS_TOKEN，或同时设置全部三个刷新变量。服务会在启动时验证配置，并指出需要修正的变量名称，但不会重复显示任何变量值。

要获取凭据，请为 Snap Marketing API 创建 OAuth 应用，使用 snapchat-marketing-api 范围授权一次，然后按照 Snap 的身份验证指南所述，用授权码换取刷新令牌。此软件包不会运行 OAuth 浏览器授权流程。续期后的令牌仅保存在内存中，因此重启后会重新使用你配置的刷新令牌。

软件包发布到 npm 后的客户端配置示例：

{
  "mcpServers": {
    "snapchat-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/snapchat-ads-mcp-server"],
      "env": {
        "SNAPCHAT_ADS_ACCOUNT_IDS": "your-ad-account-uuid",
        "SNAPCHAT_ADS_REFRESH_TOKEN": "your-refresh-token",
        "SNAPCHAT_ADS_CLIENT_ID": "your-client-id",
        "SNAPCHAT_ADS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

npm run doctor 会报告哪些变量已设置（绝不会显示其值），以及你的 Node.js 版本是否包含 2026 年 10 月的安全修复。

安全性与覆盖范围

默认情况下，写入操作会先预览。再次调用并设置 confirm: true 前，请检查确切的账户、目标和参数。 Campaign、ad squad 和广告创建时均为暂停状态。通过 snapchat_update_status 启用可能会产生广告费用，其预览会说明这一点。 如果写入操作的结果不确定，绝不会重试。写入后发生超时、网络故障、服务器错误或回复无法读取时，会将结果报告为未知：先读取实体并核对，再进行后续操作。成功写入后会按账户范围读取数据；即使读取失败，也会保留回执。 进行任何写入前，都会读取父级对象以及每个被引用的 pixel、应用、受众、媒体、创意和潜在客户表单，并检查它们是否属于所选广告账户。未知参数会被拒绝。 Snap 可能会在 HTTP 200 响应中返回失败的 request_status 或失败条目。两者都会报告为错误。明确的单项创建验证拒绝会报告为 applied: false。 以 _micro 结尾的货币字段、spend 和货币转化值均以微型货币单位表示：1,000,000 等于账户货币的 1 个单位。列表工具会返回下一页的 next_cursor；如果 Snap 返回了另一页，洞察数据会标记 partial: true。 Snap 的文档说明，每个应用每秒约可发送 20 个请求，每个访问令牌每秒约可发送 10 个请求。遇到 HTTP 429 时，会提示等待。

请求仅发送至 adsapi.snapchat.com；令牌续期请求则发送至 accounts.snapchat.com。请求不会跟随重定向，每个请求都有超时限制，回复上限为 16 MB。Snap 返回的媒体链接会原样作为数据传递，不会下载。所有错误消息中的令牌都会被隐藏。

上传内容为 base64 字节：图片上限为 5 MB，直接上传的视频上限为 10 MiB；通过分块大小为 8 MiB 的 multipart 工具上传时，视频上限为 256 MiB。每次上传后，都要调用 snapchat_get_media_status，直到 ready 为 true。网关的四个冻结文件上传工具会从托管版 Launcher 存储中读取文件，因此不属于本服务。网关的原生上传接收字节且不会获取任何 URL，因此本服务也不提供本地文件或 URL 上传。

本服务提供 Snap Marketing API 中经过审核的子集。有关确切架构，请使用 tools/list 或 server-card.json；有关单位和精选报告字段，请查看 snapchat://guide 和 snapchat://reporting-fields 资源；有关提供方详情，请参阅官方 API 参考。

Snap 官方 Ads MCP 服务

Snap 介绍了自己的 Snapchat Ads MCP 服务。下方比较仅依据 Snap 的介绍和连接指南，阅读日期为 2026 年 10 月 23 日。

	Snap 的 Ads MCP 服务	本服务
运行位置	通过 HTTP 访问的远程端点 https://mcp.snapchat.com/ads	在你的机器上通过 stdio 运行
访问权限	只读：Agent 无法创建、更新或删除任何内容。Snap 计划在未来版本中提供写入权限。	21 个读取工具；启用写入功能后可用 25 个写入工具
授权	OAuth，使用 Snap 为每个受支持的 Agent 注册的客户端 ID。组织管理员批准 Agent 后，每位成员再进行授权。	你自己的 Snap Marketing API OAuth 应用，通过环境变量配置
账户范围	成员的 Snapchat Ads 权限所允许访问的组织和广告账户	仅 SNAPCHAT_ADS_ACCOUNT_IDS 中的广告账户

托管选项

getmcpads for Snapchat Ads 管理托管连接和账户选择。 托管版与源代码发布版本可能有所不同。联系方式：[email protected]。

开发

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

所有测试均使用合成响应和模拟的 fetch 离线运行。不会读取或更改任何真实账户。

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。广告组是 Snap 的广告组。

21 个读取工具

工具	用途
snapchat_health_check	读取所选广告账户、其时区、货币和测试标记。测试账户无法投放广告。
snapchat_get_campaigns	列出所选账户中的广告系列，包括原生配置和分页信息。
snapchat_get_adsquads	列出所选账户中的广告组。
snapchat_get_ads	列出所选账户中的广告。
snapchat_get_creatives	列出所选账户中的创意素材。
snapchat_get_media	列出所选账户中的媒体。
snapchat_get_segments	列出所选账户中的受众细分。
snapchat_get_creative_elements	列出创意元素，即 Collection 广告的磁贴。
snapchat_get_interaction_zones	列出 Collection 广告的互动区域。
snapchat_get_lead_generation_forms	列出潜在客户开发表单。
snapchat_get_media_status	读取一个媒体对象及其处理状态。只有 ready: true 才允许创建创意素材。
snapchat_list_ad_creatives	解析广告背后的图片和视频，包括 Story 子项和 Collection 磁贴，并获取最新的媒体链接。
snapchat_get_targeting	读取已配置的广告组定向、受众、排除项、地理位置和版位。
snapchat_get_entity	读取一个广告系列、广告组、广告、创意素材、媒体、受众细分、创意元素、互动区域或潜在客户表单，并验证其所有权。
snapchat_get_write_schema	描述此服务接受的每种创建和编辑操作的字段及必填字段。
snapchat_get_insights	读取指定时间段的原生统计数据，并支持粒度、实体细分和可选的投放透视。
snapchat_get_mobile_apps	读取与该账户关联的 Snap App ID。
snapchat_get_pixels	读取与该账户关联的像素。
snapchat_get_targeting_specs	单独读取已存储的定向规格，包括超过 500 个条件的规格。
snapchat_get_targeting_options	获取原生定向值：国家、地区、大都市区、邮政编码、语言、性别、年龄组、兴趣和设备。
snapchat_get_setup_guide	读取目标、受众工作流、格式前置条件以及此服务的限制。

25 个写入工具

默认禁用。除非明确确认，否则调用只会预览。使用前请检查配置和确切架构。

| 工具 | 用途 | | --- | --- | | `snapchat_create_campaign` | 创建广告系列，始终处于暂停状态。 | | `snapchat_update_campaign` | 更新广告系列配置。 | | `snapchat_create_adsquad` | 在广告系列下创建广告组，始终处于暂停状态。 | | `snapchat_update_adsquad` | 更新广告组的定向、排期、预算及其他配置。 | | `snapchat_create_ad` | 在广告组下创建广告，始终处于暂停状态。 | | `snapchat_update_ad` | 更新广告配置。 | | `snapchat_create_creative` | 创建创意素材，创建前会检查其媒体、公开主页和行动号召。 | | `snapchat_update_creative` | 更新创意素材配置。 | | `snapchat_create_media` | 创建媒体对象，用于上传内容。 | | `snapchat_create_segment` | 创建受众细分：客户名单、像素、移动端或互动受众。 | | `snapchat_create_creative_element` | 为 Collection 广告创建创意元素。 | | `snapchat_create_interaction_zone` | 根据创意元素创建互动区域。 | | `snapchat_create_lead_generation_form` | 创建潜在客户开发表单。 | | `snapchat_rename_campaign` | 重命名一个广告系列。仅更改名称。 | | `snapchat_rename_adsquad` | 重命名一个广告组。仅更改名称。 | | `snapchat_rename_ad` | 重命名一个广告。仅更改名称。 | | `snapchat_rename_ad_account` | 通过将读取到的广告账户信息以新名称写回，重命名广告账户。 | | `snapchat_update_status` | 暂停或启用广告系列、广告组或广告。启用可能会产生预算支出。 | | `snapchat_upload_media` | 将 base64 图像或视频字节上传到媒体对象。 | | `snapchat_update_segment` | 重命名受众细分，或更改其描述或保留期限。 | | `snapchat_update_audience_users` | 以规范化的 SHA-256 哈希值添加或移除客户名单成员。 | | `snapchat_create_lookalike` | 根据自有客户名单创建相似受众。 | | `snapchat_init_media_upload` | 开始分段视频上传，最大支持 256 MiB。 | | `snapchat_upload_media_part` | 上传分段视频中的一个部分。 | | `snapchat_finalize_media_upload` | 完成分段视频上传。 |

资源

资源	内容
snapchat://guide	单位、分页、写入安全性、上传限制和速率限制。
snapchat://reporting-fields	为 snapchat_get_insights 精选的统计字段和细分维度。

许可证

Apache License 2.0。请参阅 NOTICE。

更多 getmcpads 项目

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。问题请联系：[email protected]。