reddit-ads

mcp-reddit-ads

Reddit Ads API v3 的 MCP 服务——通过 Claude 管理广告系列、创建广告、报告效果和定位受众。

功能

• 18 个工具，覆盖广告系列、广告组和广告的完整 CRUD 操作
• 提供按天细分的效果报告
• Subreddit、兴趣和地理位置定位
• 批量暂停/启用操作
• 默认安全：所有新实体均以 PAUSED 状态创建
• 预算以美元为单位输入（自动转换为 Reddit 的微货币格式）

安装

npm install mcp-reddit-ads

或者克隆仓库：

git clone https://github.com/mharnett/mcp-reddit-ads.git
cd mcp-reddit-ads
npm install
npm run build

配置

安全性： 切勿分享 .mcp.json 文件或将其提交到 git——该文件可能包含 API 凭据。将 .mcp.json 添加到 .gitignore。

1. Reddit OAuth 应用

在 reddit.com/prefs/apps 创建 Reddit OAuth 应用：

• 选择 "script" 类型
• 记下客户端 ID 和客户端密钥
• 使用 adsread adsedit read 作用域获取刷新令牌

2. 环境变量

通过环境变量设置凭据：

变量	描述
REDDIT_CLIENT_ID	OAuth 应用客户端 ID
REDDIT_CLIENT_SECRET	OAuth 应用客户端密钥
REDDIT_REFRESH_TOKEN	具有 ads 作用域的 OAuth 刷新令牌
REDDIT_ADS_MCP_WRITE	设置为 true 以启用修改工具（创建/更新/暂停/启用）。未设置 = 只读（默认）。

默认只读

从 v1.1.0 开始，MCP 默认以只读模式启动。10 个读取/报告/定位工具始终可用，但 8 个修改工具（创建/更新广告系列、广告组、广告，以及批量暂停/启用）不会显示在工具列表中，并且调用时会被拒绝，除非在服务的环境中设置 REDDIT_ADS_MCP_WRITE=true。这样可以防止随意的聊天消息意外更改正在投放的广告支出。请谨慎启用写入功能，仅在确实打算提交更改的会话中启用。

3. 配置文件

将 config.example.json 复制为 config.json 并填写默认值：

{
  "reddit_api": {
    "base_url": "https://ads-api.reddit.com/api/v3",
    "auth": {
      "client_id": "",
      "client_secret": "",
      "refresh_token": "",
      "user_agent": "reddit-ad-mcp/1.0"
    }
  },
  "defaults": {
    "account_id": "",
    "business_id": "",
    "report_metrics": ["impressions", "clicks", "spend", "ctr", "cpc", "ecpm"],
    "date_range_days": 7
  }
}

环境变量的优先级高于配置文件中的值。

用法

Claude Code (.mcp.json)

{
  "mcpServers": {
    "reddit-ads": {
      "command": "node",
      "args": ["/path/to/mcp-reddit-ads/dist/index.js"],
      "env": {
        "REDDIT_CLIENT_ID": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_ID -w)",
        "REDDIT_CLIENT_SECRET": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_SECRET -w)",
        "REDDIT_REFRESH_TOKEN": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_REFRESH_TOKEN -w)"
      }
    }
  }
}

Claude Desktop： 将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

工具

上下文

工具	描述
reddit_ads_get_client_context	获取账户信息并验证 API 连通性
reddit_ads_get_accounts	列出已通过身份验证的用户可访问的所有广告账户

读取

工具	描述
reddit_ads_get_campaigns	列出广告系列，可选按状态筛选
reddit_ads_get_ad_groups	列出某个广告系列的广告组
reddit_ads_get_ads	列出某个广告组的广告
reddit_ads_get_performance_report	汇总广告系列/广告组/广告的效果指标
reddit_ads_get_daily_performance	按天细分效果

写入：广告系列

工具	描述
reddit_ads_create_campaign	创建新的广告系列（默认 PAUSED）
reddit_ads_update_campaign	更新广告系列名称、预算、目标或状态

写入：广告组

工具	描述
reddit_ads_create_ad_group	创建带有定位设置的新广告组（默认 PAUSED）
reddit_ads_update_ad_group	更新广告组出价、定位设置或状态

写入：广告

工具	描述
reddit_ads_create_ad	创建包含标题、正文、URL 和媒体的新广告（默认 PAUSED）
reddit_ads_update_ad	更新广告创意或状态

批量操作

工具	描述
reddit_ads_pause_items	一次暂停多个广告系列、广告组或广告
reddit_ads_enable_items	一次启用多个广告系列、广告组或广告

定向

工具	描述
reddit_ads_search_subreddits	按关键词搜索 subreddit 以进行定向
reddit_ads_get_interest_categories	列出可用于定向的兴趣类别
reddit_ads_search_geo_targets	搜索地理定向选项（国家、地区、都市区）

关键约定

• 支出金额由 API 以微货币为单位返回（1 美元 = 1,000,000 微货币单位）。除以 1,000,000 即可得到美元金额。预算输入接受美元，并会自动转换。
• 日期和时间采用 ISO 8601 格式（YYYY-MM-DDTHH:MM:SSZ）。
• 新实体的默认状态为 PAUSED。请明确将状态设为 ACTIVE 以启用。
• 报告指标默认使用 config.json 中配置的指标集，但可按请求覆盖。

架构

• 弹性：使用 cockatiel 为 API 调用提供重试策略和断路机制
• 日志记录：通过 pino 进行结构化日志记录
• 响应截断：将大型 API 响应截断至 200KB，以符合 MCP 消息限制
• 身份验证：采用 OAuth 2.0 刷新令牌流程，自动续订访问令牌

许可证

MIT —— 详见 LICENSE。

作者

由 Mark Harnett / drak-marketing 构建。