内容
# mcp-server-reddit-ads
一个具有写入操作和分级安全控制的Reddit Ads API v3 MCP服务器，由实际的Reddit广告商构建和测试。它为MCP客户端提供对活动、广告组、广告和性能报告的读取访问，以及用于暂停、创建、预算和出价更改、定位编辑和在广告组之间复制广告的受控写入工具。
## 要求
- 一个Reddit Ads账户，具有business-admin访问权限，以便您可以注册一个应用程序。
- Node.js 20 或更新版本。
- 一个MCP客户端（Claude Code、Claude Desktop 或其他）。
## 快速入门
选择与您的设置相匹配的路径：适用于Claude Code或Claude Desktop的一键式安装路线，或适用于其他客户端的手动步骤。每条路径都安装只读权限，除非您有意启用写入权限（最后一步）。
### 使用Claude Code的简单设置（推荐）
如果您使用Claude Code，请让它完成机械工作。复制整个提示并将其粘贴到Claude Code中：
```text
为我设置mcp-server-reddit-ads MCP服务器，以便我可以从这里管理我的Reddit Ads账户。暂时以只读方式安装 - 没有写入权限。请：
1. 阅读https://github.com/camlowe/mcp-server-reddit-ads上的设置说明。
2. 检查我是否使用Node.js 20或更新版本。
3. 带我完成Reddit应用程序的注册过程，因为只有我可以完成这部分。请告诉我
确切的点击位置和两个值（客户端ID和客户端密钥）要复制。
4. 运行`npx mcp-server-reddit-ads auth`并指导我完成浏览器登录过程。
5. 将服务器添加到我的.mcp.json中，使用身份验证步骤中的凭据，写入级别设置为只读。
6. 确认服务器加载并列出我的Reddit广告账户以证明其有效。
暂时不要启用任何写入权限。当我准备好时，我会要求启用写入权限。
```
Claude 读取此README，告诉您完成只有您才能完成的部分的确切操作，运行 `npx mcp-server-reddit-ads auth`，编写您的 `.mcp.json`，并确认服务器加载。稍后，当您想要进行更改时，只需要求它提高写入级别。
### 使用Claude Desktop的简单设置
Claude Desktop无法为您运行终端命令，因此此提示在您运行一个命令和编辑一个配置文件时充当耐心指南。将它粘贴到新的Claude Desktop聊天中：
```text
我想设置mcp-server-reddit-ads MCP服务器，以便我可以与您一起管理我的Reddit Ads账户。我不是开发者，因此请一步一步地指导我，并提供简单的复制粘贴指令，并在继续之前等待我确认每个步骤。
查看https://github.com/camlowe/mcp-server-reddit-ads上的设置详情。主要步骤是：注册一个Reddit应用程序以获取客户端ID和密钥，在我的终端中运行一次`npx mcp-server-reddit-ads auth`命令以登录，并将服务器添加到我的Claude Desktop配置文件中。将其设置为只读模式，以便在您决定启用写入权限之前，我的账户中的任何内容都不会更改。
```
无论哪种方式，您仍然需要注册Reddit应用程序（步骤1）并批准浏览器登录 - 这些操作无法自动化。
### 高级设置（手动）
完整的流程，适用于其他MCP客户端或您更喜欢手动操作的过程。大约需要五分钟。
#### 1. 注册Reddit应用程序
1. 打开Reddit Ads仪表盘，网址为[ads.reddit.com](https://ads.reddit.com)，并使用具有business-admin访问权限的账户登录。
2. 打开**业务设置**（右上角的齿轮/设置菜单），然后打开**开发者应用程序**，再点击**创建应用程序**。
3. 给应用程序命名，设置**重定向URI**为`http://localhost:8080`，并选择一个主要联系人（业务管理员）。保存。
Reddit随后显示步骤2中需要的两个值：
- **客户端ID** - 在应用程序名称直接下方显示的短字符串（约22个字符，例如`Ab3xK9zQ1rStUvWxYzAbCd`）。Reddit经常显示它而不带“客户端ID”标签，因此很容易错过；它是应用程序标题下方的代码，而不是应用程序名称本身。
- **客户端密钥** - 在明确标记为**密钥**的字段中显示的较长值。请立即复制；如果丢失，您可以从同一页面重新生成新的密钥。
不要使用reddit.com/prefs/apps：它在Responsible Builder Policy下静默拒绝新应用程序，因此广告商的Ads开发门户是唯一有效的路径。
#### 2. 获取刷新令牌
运行内置的设置助手：
```bash
npx mcp-server-reddit-ads auth
```
它会要求步骤1中的客户端ID和密钥（或读取`REDDIT_CLIENT_ID`和`REDDIT_CLIENT_SECRET`，如果您已设置它们），在浏览器中打开Reddit授权页面，并在`http://localhost:8080`上等待您批准。
一旦您批准，它就会为您提供保存配置的选项：
```
我应该在哪里保存这个？（我会修改文件，保留现有内容。）
[1] Claude Code ./.mcp.json
[2] Claude Desktop <您的平台的claude_desktop_config.json>
[3] 直接打印 （不写入任何文件）
```
选择[1]或[2]，它会直接将凭证写入磁盘（备份任何现有文件到 `<file>.bak`，并保留其他服务器不变），因此任何敏感信息都无需通过您的MCP客户端传递。如果您更喜欢自己放置，请选择[3]，它会打印一个可粘贴的块。 当它检测不到TTY（例如，管道输出）时，它会跳过菜单并打印该块。
如果失败，它会告诉您如何修复两个常见原因：端口8080已被占用和重定向URI不匹配（应用程序的重定向URI必须 exactly 为`http://localhost:8080`）。
#### 3. 将服务器添加到您的MCP客户端
如果您在步骤2中选择了[1]或[2]，则此步骤已完成 - 跳至步骤4。否则，请将打印的块粘贴到客户端的配置文件中。它具有以下格式，三个凭证值已由`auth`命令预先填充：
```json
{
"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用户可以从命令行注册：
```bash
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`。有关每个级别解锁的内容，请参见[写入级别](#write-tiers)。
## 写入级别
默认情况下，写入权限是关闭的。`REDDIT_ADS_WRITE_TIER`分两步打开写入权限，以便在读取或安全级别下发生意外时无法启动花费。
高于配置级别的工具不仅被拒绝，还会从客户端的工具列表中完全隐藏。如果以某种方式调用隐藏工具，服务器会使用解锁该工具的级别拒绝它，并显示错误。
| 级别 | 允许的操作 | 规则 |
|---|---|---|
| `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` | 可选的默认账户ID（`a2_...`），以便单账户用户无需传递`account_id`。 |
## 工具
| 分组 | 工具 | 级别 |
|---|---|---|
| 诊断 | `get_server_status` | read |
| 账户 | `get_accounts`, `get_account_overview` | read |
| 实体 | `get_campaigns`, `get_campaign`, `get_ad_groups`, `get_ad_group`, `get_ads`, `get_ad` | read |
| 创意 | `get_ad_creative` | read |
| 搜索 | `find_entity` | read |
| 报告 | `get_performance_report`, `get_daily_performance`, `compare_periods`, `compare_ads` | read |
| 定位数据 | `search_subreddits`, `get_interest_categories`, `search_geo_targets` | read |
| 创建 | `create_campaign`, `create_ad_group`, `create_ad` | safe |
| 暂停/重命名 | `pause_items`, `update_name` | safe |
| 评论 | `update_ad_comments` | safe |
| 工作流 | `copy_ads` | safe |
| 恢复 | `enable_items` | spend |
| 金钱 | `update_budget`, `update_bid` | spend |
| 投放形态 | `update_targeting` | spend |
| 广告网址 | `update_ad_url` | spend |
注意：
- `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` 在活动预算优化开启时需要（自2026-07-13起为Reddit的规定）。像素ID在Reddit Ads仪表盘的事件管理器下；观察到的数据等于广告账户ID。
- `copy_ads` 将广告复制到另一个广告组（Reddit为每个复制的广告创建重复的推广帖子），并有选项重写 `utm_campaign` 和其他点击网址查询参数。
- 广告副本（标题、正文）在Reddit API中不可变 - 唯一可编辑的帖子属性是 `allow_comments`。要更改广告内容，请创建具有新内容的广告，启用它，并暂停旧广告 - 这也会保留每个消息的性能历史记录，因此这是正确的流程。
## Reddit API注意事项
客户端编码的行为已针对实时API进行验证。最令人困惑的几点：
- **更新使用`PATCH`，而非`PUT`，Reddit返回404（而非405）错误的请求方法。** 动词错误看起来与资源缺失完全相同。这是破坏上游包中所有写入的错误。
- **单个资源位于裸路径（`/ads/{id}`）；集合和创建使用帐户范围的路径（`/ad_accounts/{id}/ads`）。** 混淆它们会返回404。
- **所有货币价值均为微货币（货币单位的百万分之一）。** 此服务器在读取时将它们转换为美元，在写入时转换回美元，因此工具输入和输出以美元为单位。
- **报告指标名称为大写枚举请求，但小写响应，拼写不一致**（`CONVERSION_SIGN_UP_CLICKS` vs `CONVERSION_SIGNUP_TOTAL_VALUE`）。使用友好的小写名称；服务器验证并映射它们。
- **写入后，请信任 `configured_status` 而不是 `effective_status`。** 配置值立即更新；有效值可能会延迟数分钟。
- **广告副本无法编辑。** 创意位于推广帖子，`PATCH /posts/{id}` 只允许一个字段：`allow_comments`。标题和正文被直接拒绝。更改副本意味着发送新广告（创建，暂停）并暂停旧广告 - 这也保留了每个消息的性能历史记录，因此这确实是正确的流程。
## 开发
```bash
npm install
npm test # 单元测试和合约测试（无实时API调用）
npm run typecheck
npm run lint
npm run build
npm run smoke # 手动，调用实时API；需要环境中的真实凭证
```
## 免责声明
本软件按“原样”和“可用”状态提供，不承担任何形式的保证，如[LICENSE](LICENSE)中所述。它可能包含错误或缺陷，其提供的任何安全措施都可能失败或表现意外。使用风险自负。
该工具可以创建、重命名、暂停、恢复和重新配置实时Reddit广告实体，并可以更改预算、出价和定位。这些操作可以启动、增加或以其他方式影响实际广告支出。您单独负责：
- 因使用该服务器而产生的任何费用、广告支出或财务结果；
- 独立审查和验证它对您的账户所做的每项更改；
- 保持您的Reddit API凭证安全；以及
- 按照Reddit的规定使用Reddit Ads API。
作者对因使用该软件而造成的任何损失或意外广告支出、错误配置或暂停的活动、意外更改或其他损害不承担任何责任。
本项目是一个独立的、非官方的客户端。它与Reddit, Inc. 无关，也不受其支持或赞助。
## 许可证
MIT
