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

Related MCP server: mcp-server-reddit-ads

Prerequisites

1. A Reddit app at 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)

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

Fill in .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:

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:

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)

"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

.\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)

"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

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.