# Reddit Ads MCP Connector

Plain-language MCP for **Reddit Ads API v3**  
API base: https://ads-api.reddit.com/api/v3

Ask in simple English — no need to memorize endpoint paths or ad account IDs (when one account is configured).

## What it can do

| User asks about | Tools |
|---|---|
| Who am I / profile | `get_me` |
| Ad accounts | `list_ad_accounts`, `get_ad_account` |
| Campaigns | `list_campaigns`, `get_campaign` |
| Ad groups & ads | `list_ad_groups`, `list_ads` |
| Performance / spend | `get_performance_report` |
| Conversion pixels | `list_pixels` |

## Prerequisites

1. A Reddit app at [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps) — type **web app** or **script**
2. Note **client ID** (under the app name) and **client secret**
3. A **refresh token** with `adsread` scope (one-time OAuth — see below)

## Setup (local)

```bash
cd reddit-mcp-connector
python -m venv .venv
# Windows:
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
```

Fill in `.env`:

```env
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_secret
REDDIT_REFRESH_TOKEN=your_refresh_token
REDDIT_USER_AGENT=web:reddit-mcp-connector:v1.0.0 (by /u/YOUR_USERNAME)
REDDIT_AD_ACCOUNT_ID=t2_xxxxx   # optional but recommended
```

Start the server:

```bash
python reddit_mcp_server.py --http
```

Listens on `http://127.0.0.1:8002/mcp`.

### Get a refresh token (one time)

1. Build an authorize URL (replace placeholders):

```
https://www.reddit.com/api/v1/authorize?client_id=YOUR_CLIENT_ID&response_type=code&state=anything&redirect_uri=http://localhost:8080&duration=permanent&scope=adsread
```

2. Open it in a browser, approve access, copy the `code` from the redirect URL.
3. Exchange the code:

```bash
curl -X POST https://www.reddit.com/api/v1/access_token ^
  -u "CLIENT_ID:CLIENT_SECRET" ^
  -d "grant_type=authorization_code&code=CODE&redirect_uri=http://localhost:8080"
```

4. Save `refresh_token` from the JSON response into `.env` as `REDDIT_REFRESH_TOKEN`.

Your redirect URI in the Reddit app settings must match exactly (e.g. `http://localhost:8080`).

### Cursor (local)

```json
"reddit": {
  "url": "http://127.0.0.1:8002/mcp"
}
```

1. Keep the server running: `python reddit_mcp_server.py --http`
2. Cursor **Settings → MCP** → refresh
3. **reddit** should show green with tools like `list_campaigns`, `get_performance_report`, …

Then ask: “List my campaigns” or “Spend and impressions last 7 days”.

## Google Cloud Run

Host the same HTTP MCP endpoint on Cloud Run.

### Deploy

```powershell
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"
```

Credentials are stored in Secret Manager as JSON (`reddit-mcp-credentials`). The script prompts for missing values or reads from `.env`.

### Cursor (Cloud Run)

```json
"reddit": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}
```

### Claude custom connector

When `MCP_PUBLIC_URL` is set (deploy script does this automatically), Claude.ai OAuth + DCR is enabled.

1. Deploy with `.\deploy-cloudrun.ps1 -ProjectId "..."`
2. **Settings → Connectors → Add custom connector**
3. URL: `https://YOUR-SERVICE.run.app/mcp` (must include `/mcp`)
4. Leave OAuth Client ID empty (DCR enabled)

## Example prompts

- "List my Reddit ad accounts"
- "Show campaigns for my ad account"
- "Spend and impressions last 7 days"
- "Daily performance trend this month"
- "Break down performance by campaign"
- "List conversion pixels"

## Tools

| Tool | Purpose |
|---|---|
| `help_reddit` | What you can ask |
| `get_me` | Authenticated user |
| `list_ad_accounts` | Find ad account IDs |
| `get_ad_account` | Account details |
| `list_campaigns` | Campaign list |
| `get_campaign` | Single campaign |
| `list_ad_groups` | Ad groups |
| `list_ads` | Ads |
| `list_pixels` | Conversion pixels |
| `get_performance_report` | Metrics / spend / trends |

## Security note

Cloud Run deploy uses `--allow-unauthenticated` so the MCP URL is reachable. Claude OAuth restricts tool access to registered clients. Treat credentials and URLs as sensitive.