内容
# Reddit 广告 MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 服务器，用于 **Reddit 广告 API v3** — 读取报告 **和** 创建/编辑/暂停广告活动、广告组和广告，来自像 Claude 这样的 MCP 客户端。
> [sbmeaper/reddit-ad-mcp](https://github.com/sbmeaper/reddit-ad-mcp) 的分支，更新到真正的 v3 端点，并扩展了写入支持。
## 功能
- **读取：** 列出广告账户、广告活动、广告组、广告；灵活的性能报告，包含指标 + 分解；每日趋势。
- **写入：** 创建帖子、广告活动、广告组和广告（完整的启动流程）；更新预算、名称和状态（暂停/恢复）；删除实体。
- OAuth2，自动刷新令牌。
- 机密存储在 `.env` 文件中，默认非机密配置在 `config.json` 中。
> **安全：** 每次创建默认 `configured_status = PAUSED`，因此在您明确激活之前不会花费任何资金。货币参数以 **美元** 为单位，内部转换为 API 的微货币。
## 设置
### 1. 创建一个 Reddit “脚本”应用
1. 前往 <https://www.reddit.com/prefs/apps> → **创建另一个应用...**
2. 将 **类型** 设置为 `script`，将 **重定向 URI** 设置为 `http://localhost:8080`（仅在下面的 OAuth 流程中使用一次）。
3. 记录 **client_id**（在应用名称下）和 **client_secret**。
### 2. 获取刷新令牌（一次性 OAuth）
选择您的范围：`adsread` 表示只读，或 `adsread adsedit` 也用于创建/编辑广告。
```bash
# 1. 在登录到您的Reddit广告账户的浏览器中打开，然后点击允许。
# （URL编码范围中的空格为%20。）
https://www.reddit.com/api/v1/authorize?client_id=CLIENT_ID&response_type=code&state=random&redirect_uri=http://localhost:8080&duration=permanent&scope=adsread%20adsedit
# 2. 您将被重定向到http://localhost:8080/?code=CODE（页面不会加载 - 这没关系；从地址栏复制CODE）。
# 3. 将代码兑换为令牌：
curl -X POST https://www.reddit.com/api/v1/access_token \
-A "reddit-ad-mcp/1.0" \
-u "CLIENT_ID:CLIENT_SECRET" \
-d "grant_type=authorization_code&code=CODE&redirect_uri=http://localhost:8080"
# 4. 从JSON响应中保存refresh_token。
```
### 3. 配置凭证（`.env`）
```bash
cp .env.example .env
```
填写 `.env`（此文件被 gitignore - 永远不要提交它）：
```ini
REDDIT_CLIENT_ID=您的_client_id
REDDIT_CLIENT_SECRET=您的_client_secret
REDDIT_REFRESH_TOKEN=您的_refresh_token
REDDIT_USER_AGENT=reddit-ad-mcp/1.0
REDDIT_AD_ACCOUNT_ID=a2_xxxxxxxx # 可选默认值；工具也接受account_id
```
要找到您的广告账户 ID，请在服务器运行时询问 `get_accounts`，或者它是在 Reddit 广告仪表板中显示的 `a2_...` ID。
### 4. 安装依赖项
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 5. 在您的 MCP 客户端上注册
**Claude 代码：**
```bash
claude mcp add reddit-ads -s user -- /abs/path/to/reddit-ad-mcp/.venv/bin/python /abs/path/to/reddit-ad-mcp/server.py
```
**Claude 桌面版** (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"reddit-ads": {
"command": "/abs/path/to/reddit-ad-mcp/.venv/bin/python",
"args": ["/abs/path/to/reddit-ad-mcp/server.py"]
}
}
}
```
## 工具
### 读取
| 工具 | 描述 |
|------|-------------|
| `get_accounts` | 列出可访问的广告账户（通过您的业务）。 |
| `get_campaigns` | 列出某个账户的广告活动。 |
| `get_ad_groups` | 列出广告组（可选，按广告活动筛选）。 |
| `get_ads` | 列出广告（可选，按广告组筛选）。 |
| `get_performance_report` | 性能报告，包含自定义指标 + 分解。 |
| `get_daily_performance` | 便捷的每日趋势报告。 |
| `get_funding_instruments` | 列出某个账户的付款来源。 |
| `get_profiles` | 列出某个账户的发布配置文件（Reddit 用户）。 |
| `get_posts` | 列出配置文件下的现有帖子。 |
### 写入（需要 `adsedit` 范围）
| 工具 | 描述 |
|------|-------------|
| `create_post` | 创建一个推广的 Reddit 文本帖子；新的 ID 在返回的 `data.id` 中。 |
| `create_campaign` | 创建一个广告活动（默认为暂停）。 |
| `create_ad_group` | 创建一个广告组，包含定位 + 每日预算。 |
| `create_ad` | 将帖子（`post_id`）推广为广告。 |
| `update_campaign` | 重命名、更改支出上限、暂停/恢复。 |
| `update_ad_group` | 重命名、更改每日预算、暂停/恢复。 |
| `update_ad` | 重命名、更改点击 URL、暂停/恢复。 |
| `delete_campaign` / `delete_ad_group` / `delete_ad` | 删除实体（优先暂停）。 |
暂停/恢复是 `update_*`，其中 `configured_status` = `PAUSED` / `ACTIVE`。
**端到端启动广告：** `create_post`（新帖子的 ID 在 `data.id` 中）→ 使用该 `post_id` 在现有的广告组中创建 `create_ad`。在帖子正文中放置一个 UTM 标记的链接，以驱动和衡量点击量。
## 示例提示
- “显示我的 Reddit 广告账户以及正在运行的广告活动。”
- “我的广告上周表现如何？按广告分解。”
- “创建一个名为‘Q3 Prospecting’的暂停点击广告活动。”
- “添加一个针对 r/LLMDevs 和 r/LocalLLaMA 的广告组，每日预算为 50 美元。”
- “暂停超出预算的广告活动。”
## 报告参考
**级别：** `ACCOUNT`，`CAMPAIGN`，`AD_GROUP`，`AD`
**指标（字段）：** `impressions`，`reach`，`clicks`，`spend`，`ecpm`，`ctr`，`cpc`，视频指标（`video_watched_25/50/75/100_percent`，…），以及转化指标（`conversion_lead_clicks`，`conversion_sign_up_clicks`，`conversion_page_visit_clicks`，…）。
**分解：** `date`，`country`，`region`，`community`，`placement`，`device_os`。
> 货币字段（`spend`，`cpc`，`ecpm`）以 **微货币** 返回 — 除以 1,000,000 即可得到美元。
## 许可证
[sbmeaper/reddit-ad-mcp](https://github.com/sbmeaper/reddit-ad-mcp) 的分支，该分支不包含许可证文件。在重新分发之前，请与上游作者联系。
