Reddit Ads

Reddit Ads 的 MCP 服务（mcp-server-reddit-ads）

一个 Reddit Ads API v3 MCP 服务，支持可用的写入操作和分级安全控制，由一位真正的 Reddit 广告主构建并在实际使用中验证。它为 MCP 客户端提供读取广告系列、广告组、广告和效果报告的权限，并提供受控的写入工具，用于暂停、创建、调整预算和出价、编辑定向，以及在广告组之间复制广告。

要求

• 一个 Reddit Ads 账户，并拥有业务管理员权限，以便注册应用。
• Node.js 20 或更高版本。
• 一个 MCP 客户端（Claude Code、Claude Desktop 或其他客户端）。

开始使用

根据你的设置选择合适的方式：适用于 Claude Code 或 Claude Desktop 的粘贴一条提示词方案，或适用于其他客户端的手动步骤。无论选择哪种方式，安装后都为只读模式；除非你有意启用写入功能（最后一步），否则无法更改账户中的任何内容。

使用 Claude Code 进行简单设置（推荐）

如果你使用 Claude Code，可以让它处理机械性工作。复制以下完整提示词并粘贴到 Claude Code 中：

Set up the mcp-server-reddit-ads MCP server for me so I can manage my Reddit Ads
account from here. Install it read-only for now - no write access. Please:

1. Read the setup instructions at https://github.com/camlowe/mcp-server-reddit-ads
2. Check I'm on Node.js 20 or newer.
3. Walk me through registering a Reddit app, since only I can do that part. Tell me
   exactly where to click and which two values (client ID and client secret) to copy.
4. Run `npx mcp-server-reddit-ads auth` and guide me through the browser login.
5. Add the server to my .mcp.json using the credentials from the auth step, with the
   write tier set to read-only.
6. Confirm the server loads and list my Reddit ad accounts to prove it works.

Do not enable any write access yet. I'll ask for that later when I'm ready.

Claude 会阅读此 README，准确告知你需要亲自完成哪些步骤，运行 npx mcp-server-reddit-ads auth，编写你的 .mcp.json，并确认服务已加载。之后想要进行更改时，只需让它提高写入等级。

使用 Claude Desktop 进行简单设置

Claude Desktop 无法代你运行终端命令，因此这条提示词会让它耐心引导你运行一条命令并编辑一个配置文件。将其粘贴到新的 Claude Desktop 聊天中：

I want to set up the mcp-server-reddit-ads MCP server so I can manage my Reddit Ads
account with you. I'm not a developer, so please guide me one step at a time with
simple, copy-pasteable instructions, and wait for me to confirm each step before
moving to the next.

Look up the setup details at https://github.com/camlowe/mcp-server-reddit-ads. The
main steps are: register a Reddit app to get a client ID and secret, run a one-time
`npx mcp-server-reddit-ads auth` command in my terminal to log in, and add the server
to my Claude Desktop config file. Set it up read-only so nothing in my account can
change until I decide to turn writes on.

无论使用哪种方式，你仍需注册 Reddit 应用（见下文步骤 1）并亲自在浏览器中批准登录——这些步骤无法自动完成。

高级设置（手动）

完整流程，适用于其他 MCP 客户端，或你更喜欢手动操作的情况。大约需要五分钟。

1. 注册 Reddit 应用

1. 打开 ads.reddit.com 上的 Reddit Ads 信息中心，并使用拥有业务管理员权限的账户登录。
2. 打开 Business settings（右上角的齿轮／设置菜单），然后依次选择 Developer Applications 和 Create App。
3. 为应用命名，将 redirect URI 设置为准确的 http://localhost:8080，并选择主要联系人（业务管理员）。保存。

随后 Reddit 会显示步骤 2 所需的两个值：

• Client ID - 较短的字符串（大约 22 个字符，例如 Ab3xK9zQ1rStUvWxYzAbCd），显示在应用名称正下方。Reddit 通常不会显示“client ID”标签，因此很容易忽略；它是应用标题下方的代码，而不是应用名称本身。
• Client secret - 较长的值，显示在明确标注为 secret 的字段中。请立即复制；如果丢失，可以在同一页面重新生成一个 secret。

请勿使用 reddit.com/prefs/apps：该页面会因 Responsible Builder Policy 而静默拒绝新应用，因此 Ads 开发者门户是广告主唯一可用的途径。

2. 获取刷新令牌

运行内置设置助手：

npx mcp-server-reddit-ads auth

它会询问步骤 1 中的 client ID 和 secret（如果你已设置 REDDIT_CLIENT_ID 和 REDDIT_CLIENT_SECRET，也会读取这两个环境变量），在浏览器中打开 Reddit 授权页面，并在 http://localhost:8080 等待你批准。

批准后，它会询问是否要为你保存配置：

Where should I save this? (I'll patch the file, keeping anything already there.)
  [1] Claude Code    ./.mcp.json
  [2] Claude Desktop <your platform's claude_desktop_config.json>
  [3] Just print it  (don't write any file)

选择 [1] 或 [2]，它就会将凭据直接写入磁盘（并将任何现有文件备份为 <file>.bak，同时保留其他服务不变），这样就无需通过 MCP 客户端传递任何敏感信息。如果你想自行放置配置，请选择 [3]，它会输出可直接粘贴的配置块。如果它无法检测到 TTY（例如，输出被管道重定向），就会跳过菜单并输出配置块。

如果失败，它会告诉你如何解决两个常见原因：8080 端口已被占用，以及重定向 URI 不匹配（应用的重定向 URI 必须准确为 http://localhost:8080）。

3. 将服务添加到 MCP 客户端

如果你在第 2 步选择了 [1] 或 [2]，则已完成此操作，可跳至第 4 步。否则，将打印出的代码块粘贴到客户端的配置中。格式如下，其中三个凭据值已由 auth 命令填入：

{
  "mcpServers": {
    "reddit-ads": {
      "command": "npx",
      "args": ["-y", "mcp-server-reddit-ads"],
      "env": {
        "REDDIT_CLIENT_ID": "your-client-id",
        "REDDIT_CLIENT_SECRET": "your-client-secret",
        "REDDIT_REFRESH_TOKEN": "your-refresh-token",
        "REDDIT_ADS_WRITE_TIER": "read"
      }
    }
  }
}

Claude Code 用户也可以通过命令行注册：

claude mcp add reddit-ads \
  -e REDDIT_CLIENT_ID=your-client-id \
  -e REDDIT_CLIENT_SECRET=your-client-secret \
  -e REDDIT_REFRESH_TOKEN=your-refresh-token \
  -e REDDIT_ADS_WRITE_TIER=read \
  -- npx -y mcp-server-reddit-ads

4. 重启并验证

重启客户端以加载服务（在 Claude Code 中，按提示批准服务，并使用 /mcp 确认已加载）。然后让它列出你的 Reddit 广告账户。你应该会看到自己的账户 ID（a2_...）。如果你只管理一个账户，请在配置中将 REDDIT_ADS_ACCOUNT_ID 设为该 ID，然后重启，这样以后就无需在请求中再指定账户。

5. 尝试一些只读查询

你已连接，且当前为只读模式。可以先试着询问：

• “概述一下我的 Reddit 广告账户。”
• “显示过去 7 天按广告系列划分的效果。”
• “我的哪些广告组目前处于启用状态？”

大多数人日常使用时都会保持此状态。需要进行更改时，再开启写入功能。

6. 需要时开启写入功能

全新安装无法暂停、创建或编辑任何内容。若要允许更改，请在配置中提高 REDDIT_ADS_WRITE_TIER 的值，然后重启。先使用 safe（此级别下的任何操作都无法开始或增加支出），只有在打算恢复投放或更改预算、出价或定向时，才切换到 spend。各级别具体开放的功能，请参阅写入级别。

写入级别

默认情况下，写入功能处于关闭状态。REDDIT_ADS_WRITE_TIER 分两步开放写入功能，因此在只读或安全级别发生意外时，不会开始花费资金。

高于配置级别的工具不仅会被拒绝使用，还会从客户端的工具列表中完全隐藏。只读会话会显示 18 个工具；模型甚至无法尝试调用 update_budget，因为它不知道该工具存在。如果某个隐藏工具仍被调用，服务会拒绝该请求，并在错误中指出解锁此工具所需的级别。

级别	允许的操作	规则
read（默认）	不允许写入。	仅限读取。
safe	暂停、创建（创建后暂停）、重命名、复制广告。	无法开始或扩大投放。
spend	safe 级别允许的所有操作，以及启用、预算、出价和定向更改。	可以开始、恢复或调整投放。

环境变量

变量	含义
REDDIT_CLIENT_ID、REDDIT_CLIENT_SECRET、REDDIT_REFRESH_TOKEN	必需。如果缺少任何一项，启动将失败，并提示使用 auth 命令。
REDDIT_ADS_WRITE_TIER	read（默认）、safe 或 spend。
REDDIT_ADS_ACCOUNT_ID	可选的默认账户（a2_...），让单账户用户无需传入 account_id。

工具

分组	工具	级别
诊断	get_server_status	读取
账户	get_accounts、get_account_overview	读取
实体	get_campaigns、get_campaign、get_ad_groups、get_ad_group、get_ads、get_ad	读取
创意	get_ad_creative	读取
搜索	find_entity	读取
报告	get_performance_report、get_daily_performance、compare_periods、compare_ads	读取
定向数据	search_subreddits、get_interest_categories、search_geo_targets	读取
创建	create_campaign、create_ad_group、create_ad	安全
暂停 / 重命名	pause_items、update_name	安全
评论	update_ad_comments	安全
工作流	copy_ads	安全
恢复	enable_items	花费
资金	update_budget、update_bid	花费
投放设置	update_targeting	花费
广告 URL	update_ad_url	花费

说明：

• get_campaigns、get_ad_groups 和 get_ads 接受可选的 status 筛选条件（ACTIVE、PAUSED 或 ARCHIVED），并在客户端根据 configured_status 进行筛选。
• 工具结果最多为 200,000 个字符；结果被截断时会注明，并建议缩小查询范围。
• get_performance_report 接受易读的小写指标名称（impressions、clicks、spend、cpc、conversion_page_visit_clicks 等），并会在发起调用前于本地验证；如果名称拼写错误，还会提示最接近的匹配项。
• create_ad_group 必须提供 conversion_pixel_id；启用广告系列预算优化时，create_campaign 也必须提供该参数（这是 Reddit 自 2026-07-13 起的要求）。可在 Reddit Ads 信息中心的 Events Manager 中找到像素 ID；在观测到的数据中，它与广告账户 ID 相同。
• copy_ads 会将广告复制到另一个广告组（Reddit 会为每个副本创建一条重复的推广帖子），并可选择重写 utm_campaign 和其他点击 URL 查询参数。
• 通过 Reddit API 无法修改广告文案（标题、正文）；唯一可编辑的帖子属性是 allow_comments。如需更改广告内容，请使用新文案创建新广告、启用该广告，然后暂停旧广告。

Reddit API 注意事项

客户端会处理已通过线上 API 验证的行为。以下问题最容易引起混淆：

• 更新使用 PATCH，绝不使用 PUT；如果使用了错误的 HTTP 方法，Reddit 会返回 404（而非 405）。 HTTP 方法错误看起来与资源不存在完全相同。这是导致上游软件包的所有写入操作失效的错误。
• 单个资源位于裸路径（/ads/{id}）；集合和创建操作使用账户范围的路径（/ad_accounts/{id}/ads）。 混用会返回 404。
• 所有金额均以微货币计量（货币单位的百万分之一）。 此服务会在读取时将其转换为美元，并在写入时转换回来，因此工具的输入和输出单位均为美元。
• 请求中的报告指标名称是大写枚举值，响应中则为小写，且拼写不一致（CONVERSION_SIGN_UP_CLICKS 与 CONVERSION_SIGNUP_TOTAL_VALUE）。请使用易读的小写名称；服务会验证并映射这些名称。
• 写入后，请以 configured_status 为准，而不是 effective_status。 配置值会立即更新；生效值可能延迟数分钟。
• 无法编辑广告文案。 创意内容位于推广帖子上，而 PATCH /posts/{id} 仅允许修改一个字段：allow_comments。标题和正文会被直接拒绝。更改文案时，需要发布一条新广告（通过 create_ad 创建，初始状态为暂停），并暂停旧广告；这样还可以按文案保留效果历史记录，因此无论如何这都是正确的工作流。

开发

npm install
npm test          # unit and contract tests (no live API calls)
npm run typecheck
npm run lint
npm run build
npm run smoke     # manual, hits the live API; needs real credentials in env

免责声明

本软件按“原样”和“可用状态”提供，不作任何形式的保证，具体规定见 LICENSE。本软件可能包含错误，其提供的任何安全防护或控制措施都可能失效或出现意外行为。使用风险由你自行承担。

此工具可以创建、重命名、暂停、恢复和重新配置正在投放的 Reddit 广告实体，也可以更改预算、出价和定向设置。这些操作可能会开始、增加或以其他方式影响实际广告支出。你需独自负责：

• 因使用此服务而产生的任何费用、广告支出或财务结果；
• 独立审核并验证此工具对你的账户所做的每一项更改；
• 妥善保管你的 Reddit API 凭据；以及
• 确保你使用 Reddit Ads API 的方式符合 Reddit 的条款。

对于因使用本软件而导致的广告支出损失或意外支出、广告系列配置错误或暂停、意外更改或任何其他损害，作者概不负责，包括其安全控制措施未能阻止某项操作的情况。

本项目是独立的非官方客户端，与 Reddit, Inc. 无关联，未经其认可，也未获得其赞助。

许可证

MIT