Reddit Ads Insights MCP

Read-only, analysis-first MCP server for the Reddit Ads API v3. Ask your AI assistant about your Reddit Ads performance — campaigns, subreddit-level breakdowns, reports, targeting — with a server that cannot modify anything.

Works with any MCP client: Claude, ChatGPT, Cursor, VS Code, Windsurf, Gemini CLI, and anything else that speaks MCP — see docs/CONNECT.md. Host it anywhere a container runs; a step-by-step free-tier Google Cloud Run guide is included.

Unofficial community project. Not affiliated with, endorsed, certified, or supported by Reddit, Inc. "Reddit" is a trademark of Reddit, Inc. You are responsible for your own compliance with Reddit's Ads API Terms and Developer Terms.

Why this exists

• Permanently read-only. Requests only the adsread OAuth scope, and every outgoing API call must match a version-controlled allowlist of read operations (all 99 spec operations are explicitly classified; CI fails if a write becomes reachable). There is no write mode to misconfigure.

• Single advertiser per deployment. You deploy it in your own Google Cloud project (or run it locally); your credentials never touch anyone else's infrastructure. A mandatory account allowlist blocks cross-account access.

• Built for analysis. Flexible reports across ~450 metrics with up to 3 breakdown dimensions (COMMUNITY — i.e. subreddit — DATE, HOUR, COUNTRY, PLACEMENT, KEYWORD, and more), plus safety ceilings so an AI client loop can't burn your rate limits or your wallet.

• Personal-use cost profile. Scale-to-zero Cloud Run, max 1 instance; normal personal use lands at ~$0/month.

Related MCP server: flin-google-ads-mcp

Tools (27)

Structure: list_ad_accounts · list_campaigns · list_ad_groups · list_ads

Reporting: get_report · get_daily_performance

Analysis: compare_periods · rank_performance · analyze_trends · analyze_pacing · analyze_conversions · analyze_video · analyze_creatives · get_creative_context · get_account_history

Diagnostics: get_tracking_health · diagnose_delivery · list_custom_audiences · get_catalog_health

Targeting & forecasting: search_targeting · get_community_suggestions · get_reach_estimate · get_bid_suggestions · get_keyword_suggestions · get_feature_access · get_saved_audiences · list_lead_gen_forms

Resources: reddit-ads://report-fields, reddit-ads://capabilities. Live-API quirks are documented in docs/API_NOTES.md.

Setup overview

1. Create a Reddit Ads developer application — in Reddit Ads Manager, open your business settings → Developer Applications → create an app. Note the client ID and secret.

2. Authorize with adsread only and obtain a refresh token (see docs/AUTHENTICATION.md). The server refuses to run with a write-capable grant.

3. Find your ad account ID (a2_…) in the Ads Manager account switcher.

4. Run it (either way):

   • Locally (stdio) for desktop MCP clients:

     pip install .
     cp .env.example .env   # fill in values, then source it
     reddit-ads-mcp

   • Hosted — any container platform works (the image is a plain Dockerfile). A complete free-tier walkthrough for Google Cloud Run is in docs/DEPLOY_GCP.md (~15 min); the same env-var contract applies on Fly.io, Railway, Render, or your own VPS. Hosted mode is required for chat apps like claude.ai and ChatGPT, which can't run local servers.

5. Connect your AI tool — per-client instructions for Claude, ChatGPT, Cursor, VS Code, Gemini CLI, and generic MCP clients: docs/CONNECT.md.

Remote authentication (pick exactly one)

Secret-path mode treats the URL as the credential: it can appear in client settings, browser history, and infrastructure logs. Generate it with python3 -c "import secrets; print(secrets.token_urlsafe(32))", rotate it periodically, and prefer bearer mode when possible.

Safety & privacy properties

• Only adsread; startup fails if the token grant includes write scopes.

• Exact-match operation allowlist; pagination URLs are validated (HTTPS, host, path family) before being followed.

• Mandatory ALLOWED_ACCOUNT_IDS; every tool call re-checks the account.

• Rate/loop safeguards: 60 tool calls per rolling hour, 20 upstream requests per call, duplicate-call suppression, 90-day report ceiling, bounded rows, pages, and response size.

• No database, no persistent cache, no payload logging. Report rows and entity names never appear in logs.

Data disclosure note: this server returns your advertising metrics to the MCP client you connect — typically a hosted AI assistant. Review your AI provider's data handling and your own obligations under Reddit's terms before connecting a production account. Do not share one deployment across unrelated advertisers, and do not use returned data to train models without the necessary permissions.

Development

pip install -e ".[dev]"
python3 -m unittest discover tests      # or: pytest
python3 scripts/check_openapi_drift.py  # spec/registry drift gate

The pinned OpenAPI spec lives in openapi/ with its checksum. Any spec update requires reclassifying changed operations and regenerating the registry in the same commit — CI enforces this.

Acknowledgments

No code was reused from other projects, but this server stands on prior art worth crediting:

• mkerchenski/RedditAdsMcp (C#, MIT) and sbmeaper/reddit-ad-mcp (Python) — the first open-source Reddit Ads MCP servers; their setup flows informed our authentication documentation.

• Public field references from Supermetrics and Adzviser helped map the reporting surface before the official OpenAPI spec settled every enum (the live API disagreed with third-party docs in places — see docs/API_NOTES.md).

• Built with the official MCP Python SDK.

Dependencies

Three direct runtime dependencies, declared in pyproject.toml: mcp (pinned >=1.9,<2; SDK 2.0 is API-incompatible), httpx, and pydantic. A committed uv.lock pins the full transitive tree for reproducible builds; Dependabot proposes version updates weekly. The small footprint is deliberate — this server handles ad-account credentials, so every dependency is attack surface.

License

MIT — see LICENSE.