Pinterest Ads

影片展示的是使用示例数据的托管版 getmcpads。其中的 MCP Apps 涵盖创意素材库、提醒、Google Sheets 导出和批量启动等功能，属于托管产品。本仓库提供独立的原生 API 工具。

29 个读取工具 · 30 个写入工具，默认禁用。

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

更新内容

v2.1.1：Zod 4 安全更新 · 2026 年 10 月 26 日

• 将 zod 更新到 4.6.7。所有早于 4.6.6 的 Zod 版本均受高危安全公告 GHSA-mrhx-c7xc-m3w5 影响：验证超出限制的大型集合可能耗尽内存，而且 Zod 3 没有任何版本包含此修复。npm audit --omit=dev 再次报告没有漏洞。
• 保持 Zod 3 的验证行为不变。参数默认值在使用前仍会经过验证和补全，因此省略对象时仍必须提供其必需字段。
• 参数为可选项或设有默认值时，仍保留该参数自己的描述。Zod 4 只会在包装后的模式上存储描述，否则共享的回退描述可能会覆盖它。
• 通过 MCP 发布的工具名称、参数和描述均未改变。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，其中部分约束的表述有所不同。

早期版本

版本	日期	主要内容
2.1.0	2026 年 10 月 23 日	重命名工具并支持原生视频上传
2.0.1	2026 年 9 月 23 日	恢复公开仓库
2.0.0	2026 年 9 月 20 日	网关同步和安全修复
1.1.0	2026 年 9 月 13 日	平台能力同步和质量契约
1.0.2	2026 年 8 月 30 日	通过 MCP 公布软件包版本。
1.0.1	2026 年 8 月 30 日	为官方 MCP Registry 添加 server.json 和 mcpName，名称为 com.getmcpads/pinterest-ads。
1.0.0	2026 年 8 月 29 日	首次开源发布

完整变更日志 · 所有版本

源同步：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1 或 26.12.1，或这些版本线中的更高版本。在较旧的运行时上，服务仍会启动，并向 stderr 写入警告。CI 覆盖 Node 22、24 和 26。

此版本没有破坏性变更，现有配置仍可正常使用。计划在 3.0.0 中进行两项变更；如果变更适用于你的配置，服务会在启动时分别通过 stderr 发出提示：

• PINTEREST_AD_ACCOUNT_IDS 将成为必填项。现在就设置它，将服务限制为所列的广告账户。在此之前，PINTEREST_AD_ACCOUNT_ID 仍是默认账户，而非限制条件。
• PINTEREST_ENABLE_WRITES 只有设为 true 才会启用写入。请将 1、yes 或 on 替换为 true。

pinterest://attribution 资源现在将默认项命名为 defaultAttribution。旧的 defaults 键会保留为别名，直到 3.0.0。

重新使用已保存的参数前，请先查看当前工具架构。写入功能仍为可选，且需要明确确认。托管式创意素材集成和 MCP Apps UI 不在此版本范围内。

安装此版本

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

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/pinterest-ads-mcp-server.git
cd pinterest-ads-mcp-server
npm ci
npm run build

配置 MCP 客户端，使其运行 node 并传入 dist/cli.js 的绝对路径，以及下文所述的平台凭据。

更倾向于使用托管连接？ 通过托管服务 getmcpads 使用 Pinterest Ads。连接你的账户，选择助手可访问的数据，然后使用托管 MCP 连接。当前功能和方案请参阅网站。

你将获得

29 个读取工具	报告、广告系列和广告组、受众、定向、关键词、转化、目录、商业资产、账单、Pin、趋势和视频处理状态
30 个写入工具	默认关闭。创建暂停状态的广告系列、广告组和广告，并更改其状态、预算、设置和名称。上传视频并管理看板、Pin 和目录。每项操作都会先预览再应用
7 个资源	模型可读取的实时目录：报告列、归因窗口、创意素材、目录报告、界面映射、操作指南
兼顾自然流量与付费流量	Pin 分析和趋势，不局限于广告账户
从设计上保护隐私	完全不公开潜在客户记录，默认会对成员标识符进行脱敏

刻意保留原始列名

Pinterest 使用自己的方式命名报告列，本服务直接接受这些列名， 而不是在其上另造易读的别名。API 中存在的列在这里就能使用；不存在的列会立即报错， 不会被悄悄转换成其他内容。

pinterest://reporting-columns 会列出可用列，pinterest_validate_report 会在请求运行前对其进行检查。

---

隐私保护内置于工具返回内容中

有两项保护措施，运作方式各不相同。

绝不公开潜在客户记录。 pinterest_get_lead_assets 会返回潜在客户表单和订阅配置， 但绝不返回潜在客户导出数据，因为这些记录包含终端用户提交的个人信息。这是排除，而非脱敏：这些数据根本不会通过此服务离开 Pinterest。

默认对商业成员标识符进行脱敏。 读取成员、资产成员或邀请时，成员 ID、电子邮件地址和 用户名会在传给模型前被替换。includePersonalIdentifiers: true 会返回原始值，其默认值为 false。 这些是同事的地址，因此默认设置更安全。

获取令牌

你需要一个具有 ads:read 作用域的 Pinterest 访问令牌。

1. 在 Pinterest 开发者门户中创建应用。
2. 记下 App ID 和 App secret。
3. 登录有权访问你的广告账户的账号，然后运行 OAuth 流程。 请求 ads:read；仅当你计划启用写入时才请求 ads:write。
4. 保存 访问令牌；如果希望服务续期，还要保存 刷新令牌。

📖 Pinterest API 身份验证

你可以只使用 PINTEREST_ACCESS_TOKEN 运行，但该令牌会过期。同时提供 PINTEREST_REFRESH_TOKEN、PINTEREST_APP_ID 和 PINTEREST_APP_SECRET，服务就能自行续期令牌；日常使用时建议这样配置。

首次调用时运行 pinterest_health_check。它会验证令牌并列出你可以访问的广告账户，且不会输出令牌。

---

设置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pinterest-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/pinterest-ads-mcp-server"],
      "env": {
        "PINTEREST_ACCESS_TOKEN": "your-token-here",
        "PINTEREST_AD_ACCOUNT_IDS": "your-ad-account-id"
      }
    }
  }
}

PINTEREST_AD_ACCOUNT_IDS 是可选但推荐的配置。它会将服务限制为所列的广告账户，且 3.0.0 版本将要求设置此变量。

重启 Claude Desktop。向它提问：“列出我的 Pinterest 广告账户”。

Claude Code

claude mcp add pinterest-ads --env PINTEREST_ACCESS_TOKEN=your-token --env PINTEREST_AD_ACCOUNT_IDS=your-ad-account-id -- npx -y @getmcpads/pinterest-ads-mcp-server

Cursor

项目中的 .cursor/mcp.json，格式与上面的 Claude Desktop 配置相同。

从源代码运行

git clone https://github.com/get-mcp-ads/pinterest-ads-mcp-server.git
cd pinterest-ads-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

配置

变量	默认值	含义
PINTEREST_ACCESS_TOKEN	无	具有 ads:read 作用域的访问令牌
PINTEREST_REFRESH_TOKEN	无	与下面两个变量一起使用时，可让服务续期令牌
PINTEREST_APP_ID	无	App ID，续期时必需
PINTEREST_APP_SECRET	无	App secret，续期时必需
PINTEREST_AD_ACCOUNT_IDS	无	推荐设置。服务可以使用的广告账户 ID，以逗号分隔。设置后，请求中指定其他账户会被拒绝。3.0.0 版本将要求设置此变量
PINTEREST_AD_ACCOUNT_ID	无	可选默认值，可省去每次调用时传入该值。如果已设置 PINTEREST_AD_ACCOUNT_IDS，则此值必须是其中一个账户
PINTEREST_ENABLE_WRITES	未设置	设为 true 以注册 30 个写入工具。1、yes 和 on 也可使用，但已弃用。无法识别的值会导致服务停止
PINTEREST_ENVIRONMENT	production	production 或 sandbox；凭据必须是在对应环境中签发的
LOG_LEVEL	info	debug、info、warn、error

必须提供访问令牌，或完整的刷新凭据组合。两者都未提供时，服务会拒绝启动。 如果未设置 PINTEREST_AD_ACCOUNT_IDS，令牌可访问的所有广告账户都能访问；服务启动时会通过 stderr 提示这一点。

npm run doctor

---

写入工具为何会先提供预览

写入工具默认禁用。设置 PINTEREST_ENABLE_WRITES=true 即可启用，并且除了 ads:read，还需授予 ads:write。

启用后，每个写入工具都会返回预览，不会进行任何更改：

// pinterest_update_adgroup_budget { adAccountId: "549…", adGroupId: "268…", dailyBudget: 50 }
{
  "applied": false,
  "action": "pinterest_update_adgroup_budget",
  "change": { "adAccount": "549…", "adGroup": "268…",
              "field": "budget_in_micro_currency", "amount": 50,
              "inMicroCurrency": 50000000 },
  "message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}

只有第二次调用携带 confirm: true 时，才会修改线上账户。

这是有意为之。助手会编写这些调用，而它可能选错广告账户、选错广告系列，或把预算金额的数量级弄错。强制提供预览可以在造成损失之前让错误显现，也为人工审核者提供一个协议本身无法保证的停止点。

还有两道防护措施：

• pinterest_create_campaign 始终会创建状态为 PAUSED 的广告系列。 没有选项可以创建启用状态的广告系列。
• 金额会自动转换为微单位。 Pinterest 以百万分之一为单位保存金额，因此账户货币中的 12.50 会转换为 12500000。预览会同时显示两者，因此在应用更改前就能发现百万倍的错误。如果同时提交每日预算和总预算，系统会拒绝请求，而不会擅自决定使用哪一个。

工具	更改内容
pinterest_update_campaign_status / pinterest_update_adgroup_status	暂停、重新启用或归档
pinterest_update_campaign_budget / pinterest_update_adgroup_budget	每日预算或总预算
pinterest_create_campaign	创建广告系列，状态始终为 PAUSED
pinterest_rename_campaign / pinterest_rename_adgroup / pinterest_rename_ad	仅更改名称
pinterest_prepare_video_upload / pinterest_upload_video	注册视频，然后将其发送到 Pinterest 返回的上传目标位置

---

工具

以下列出了所有工具。完整的参数和输出架构请参阅 server-card.json。

29 个读取工具

| 工具 | 用途 | | --- | --- | | `pinterest_health_check` | 只读 Pinterest Ads 健康检查。 | | `pinterest_list_ad_accounts` | 列出配置的凭据可访问的 Pinterest 广告账户。 | | `pinterest_get_delivery_metrics` | 读取 Pinterest resources/delivery_metrics。 | | `pinterest_validate_report` | 验证并预览 Pinterest 报告的执行方式。 | | `pinterest_run_report` | 运行只读 Pinterest Ads 报告。 | | `pinterest_get_creative_assets` | 获取 Pinterest 创意素材及可用时段的表现数据。 | | `pinterest_run_catalog_report` | 按 PRODUCT_GROUP 或 PRODUCT_ITEM 运行 Pinterest 商品目录报告。 | | `pinterest_get_catalog_inventory` | 列出 Pinterest 商品目录库存：商品目录、商品组、商品组促销，以及可选的商品样本。 | | `pinterest_run_conversion_product_report` | 通过 reports/brand_category_sku，按品牌、类别、品牌+类别、SKU 或 SKU 组运行 Pinterest 异步转化商品报告。 | | `pinterest_list_ad_creatives` | 列出广告账户在所有状态下的广告创意（除非明确要求，否则 API 会静默省略 ARCHIVED 广告），并解析其 Pin 媒体：最高 1200px 的公开 i.pinimg.com 图片 URL、视频封面，以及应用获准读取时的 video_url。 | | `pinterest_get_write_schema` | 在编写写入请求前，读取 Pinterest v5 官方原生请求架构和 Sandbox 限制。 | | `pinterest_get_account_entities` | 读取 Pinterest 广告账户实体和配置。 | | `pinterest_run_targeting_report` | 为广告账户、广告系列、广告组或广告运行实时定向分析，并按年龄、性别、地点、兴趣、关键词、受众、版位、设备或其他 Pinterest 定向类型细分。 | | `pinterest_get_targeting_options` | 读取 Pinterest 官方定向选项目录，涵盖应用类型、性别、语言区域、年龄、地点/地理位置、兴趣、关键词或受众。 | | `pinterest_get_keyword_intelligence` | 读取已分配的定向关键词、Pinterest 按国家/地区划分的关键词指标、推荐词或相关词。 | | `pinterest_get_audiences` | 读取受众、客户名单、共享受众和由 Business 接收的受众库存，不上传受众数据，也不更改受众成员。 | | `pinterest_get_audience_insights` | 读取汇总的 Pinterest Audience Insights，涵盖广告主的总体受众或互动受众、Pinterest 的总体受众，或范围/类型端点。 | | `pinterest_estimate_delivery` | 运行不会更改数据的 Pinterest 规划计算：广告组受众规模、出价下限或广告系列投放预估。 | | `pinterest_get_conversion_setup` | 检查 Pinterest 转化衡量配置：转化标签、符合 oCPM 条件/页面访问标签、Event Quality Score、广告主自定义事件，以及转化删除请求状态。 | | `pinterest_get_catalog_diagnostics` | 读取详细的商品目录库存和诊断信息：商品目录、Feed、Feed 处理结果、商品问题、商品组、商品数量/商品、可用筛选值，以及商品目录商品查询。 | | `pinterest_run_specialized_export` | 启动或检查不会更改数据的 Pinterest 数据作业，用于营销组合建模（MMM）、广告主实体批量下载或商品目录诊断。 | | `pinterest_get_lead_assets` | 读取潜在客户表单定义和潜在客户订阅配置。 | | `pinterest_get_business_assets` | 读取 Pinterest Business Access 库存：雇主/关联企业、资产、成员、合作伙伴、已分配资产、已接收受众和邀请。 | | `pinterest_get_billing_and_orders` | 读取账单资料/发票、发票下载 URL、订单行、广告抵扣折扣，以及 SSIO 账户/订单状态。 | | `pinterest_get_pin_analytics` | 读取付费 Pin 分析、有机多 Pin/单 Pin 分析、用户账户分析、热门 Pin 或热门视频 Pin。 | | `pinterest_get_organic_inventory` | 读取与广告搭配使用的 Pinterest 有机内容：Pin、图板、图板上的 Pin、Pin 商品标签或搜索结果。 | | `pinterest_get_trends` | 读取 Pinterest Trends：受支持地区的热门增长/每月/每年/季节性关键词、增长中的商品类别、商品类别详情、精选主题或编辑文章。 | | `pinterest_get_platform_resources` | 读取 Pinterest 平台元数据和就绪情况资源：支持的广告账户国家/地区、投放指标定义、指标就绪情况、潜在客户表单问题、媒体上传元数据、商务集成元数据或已认证的用户账户。 | | `pinterest_get_video_upload` | 读取此广告主关联的已上传视频的处理状态。只有 ready:true 才允许创建视频 Pin。 |

30 个写入工具

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

工具	用途
pinterest_create_campaign	创建一个已暂停的广告系列。
pinterest_update_campaign_status	更新现有广告系列的状态。
pinterest_update_adgroup_status	更新现有广告组的状态。
pinterest_update_ad_status	更新现有广告的状态。
pinterest_update_campaign_budget	以账户主要货币单位设置一个每日或终身广告系列预算，且只能设置其中一种。
pinterest_update_adgroup_budget	以账户主要货币单位设置一个每日或终身广告组预算，且只能设置其中一种。
pinterest_update_campaign_configuration	更新原生广告系列设置。
pinterest_update_adgroup_configuration	更新原生广告组设置。
pinterest_update_ad	更新原生广告设置。
pinterest_rename_campaign	重命名一个广告系列。只有名称会更改。
pinterest_rename_adgroup	重命名一个广告组。只有名称会更改。
pinterest_rename_ad	重命名一个广告。只有名称会更改。
pinterest_create_adgroup	创建一个已暂停的广告组，并明确指定原生出价、定向、预算和排期。
pinterest_create_ad	根据可访问的 Pin 创建一个已暂停的广告。
pinterest_create_product_group_promotion	根据目录商品组创建一个已暂停的购物或合集推广。
pinterest_update_product_group_promotion	更新目录商品组推广。
pinterest_create_collection_ad	创建一个已暂停的合集，明确选择图片或视频作为主视觉 Pin，并指定一个可访问的目录商品组。
pinterest_create_board	在所选广告主上下文中创建 /boards。
pinterest_update_board	在所选广告主上下文中更新 /boards。
pinterest_create_pin	在所选广告主上下文中创建 /pins。
pinterest_update_pin	更新一个 Pin。
pinterest_register_media	注册媒体上传；返回的 upload_url/parameters 并不能确认视频已上传或准备就绪。
pinterest_prepare_video_upload	为本地文件或 HTTPS URL 注册原生 Pinterest 视频上传，并将其不透明回执保留在内存中。
pinterest_upload_video	将已注册的视频流式传输到保存在 uploadReceipt 中的原生目标位置，且不使用 Pinterest 访问令牌。
pinterest_create_catalog	在所选广告主上下文中创建 /catalogs。
pinterest_create_catalog_feed	在所选广告主上下文中创建 /catalogs/feeds。
pinterest_update_catalog_feed	在所选广告主上下文中更新 /catalogs/feeds。
pinterest_create_product_group	在所选广告主上下文中创建 /catalogs/product_groups。
pinterest_update_product_group	在所选广告主上下文中更新 /catalogs/product_groups。
pinterest_batch_catalog_items	提交原生 CREATE/UPDATE/UPSERT/DELETE 目录商品操作。

7 个资源

URI	内容
pinterest://manifest	此服务公开的内容及其当前模式
pinterest://reporting-columns	API 接受的所有报告列
pinterest://attribution	归因窗口及其默认值
pinterest://creative-assets	创意素材的结构
pinterest://catalog-reporting	目录专用报告列
pinterest://surface-map	各工具涵盖的 API 部分
pinterest://recipes	分步工作流

---

安全

• 令牌绝不会被记录到日志中，无论日志级别如何，也不会写入磁盘。
• 凭据只会发送到 Pinterest API：沙盒模式下为 api.pinterest.com 或 api-sandbox.pinterest.com。如果源码中出现其他主机，测试将导致构建失败。
• PINTEREST_AD_ACCOUNT_IDS 会限制可访问的广告账户。 设置该变量后，任何指定其他账户的请求都会在发送前被拒绝，发现功能也只会返回列出的账户。
• 不会跟随任何重定向。 每个外发调用都会设置 redirect: "error"，因此重定向无法将你的令牌转发到其他主机。如果任何 fetch 调用未设置此项，测试将导致构建失败。
• 异步报告 URL 会在获取前经过验证。 Pinterest 会返回一个由其选择主机的下载 URL；该值是来自 API 的数据，不可盲目信任。仅允许 HTTPS，不允许私有或环回地址，不跟随重定向，也不附带凭据。
• 视频上传会发送到 Pinterest 返回的目标地址：使用前会检查其是否为 Amazon S3 主机，并使用签名表单字段，绝不发送访问令牌。你传入的视频 URL 也会接受与报告 URL 相同的检查。每个请求都有超时和响应大小限制。
• 不收集遥测数据。 除 Pinterest API 外，服务只会联系 Pinterest 返回的报告和上传 URL，以及你传给上传工具的视频 URL。

完整政策（包括个人数据的处理方式）请参阅：SECURITY.md。

---

想要使用托管式多平台版本？

如果你想使用此源而无需运行本地服务，请试用托管版 Pinterest Ads。 getmcpads 还可以通过一个 MCP URL 连接广告、Search Console 和 GA4。 网站上列出了可用源和套餐限制；仍需连接账户。

1. 按照 Pinterest Ads 连接指南操作。
2. 选择助手可读取的账户或资源。
3. 连接 Claude、 ChatGPT 或 Codex。
4. 尝试进行只读检查：“使用你选择的广告账户检查广告系列效果。指出缺失的数据，不要进行任何更改。”

选择付费套餐前，请查看当前托管工具目录 和定价。 此 Apache 2.0 适配器仍可使用你自己的凭据独立发挥作用。

---

参与贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。 报告任何安全相关问题前，请阅读 SECURITY.md。

许可证

Apache License 2.0。另请参阅 NOTICE。

Pinterest 是 Pinterest, Inc. 的商标。 本项目与 Pinterest, Inc. 无关，也未获得其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 合约和桌面套件

每个工具都会声明读写注解、参数说明和结构化输出架构。成功调用会将有效负载作为 structuredContent.result 暴露；错误会保留 isError: true。生成的服务卡片仅包含定义。

运行 npm run bundle -- /path/to/output，即可根据当前目录构建 .mcpb 桌面套件。安装时在本地输入凭据。除非明确启用，否则写入工具会保持禁用状态。

More from getmcpads

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

Maintained by Emmanuel at getmcpads. Questions: [email protected].