UGC Scraper MCP server

A Model Context Protocol server for the UGC Scraper Reddit API. It lets Claude Desktop (and any MCP client) scrape a Reddit post and its full comment thread into clean, consistent JSON, list subreddit, user and search results, read profiles and subreddit rules, re-check scores in bulk, and read your durable scrape history and usage — without leaving the model.

It is a thin, authenticated HTTP client over https://api.ugcscraper.com. No Reddit API keys, no infrastructure of your own, no scraping logic in this package.

Tools

Every customer data endpoint of the API is exposed as one tool. Key management (create / revoke / rotate a key) is deliberately not exposed: use the API keys page.

| Tool | What it does | Permission | Quota | |------|--------------|------------|-------| | scrape_reddit_url | Scrape a Reddit post URL (or bare post id) into one JSON schema: post + full comment thread. The same post within 10 minutes is served from cache. fresh: true reads the numbers Reddit shows right now (10 to 30 s, same quota). | Post | 1 per success | | refresh_posts | Current score, comment count and removed status for 1–150 posts in one call. Always bypasses the cache; each success is stored as a new history snapshot. | Post | 1 per input | | list_subreddit_posts | A subreddit's posts as summaries (no comments). sort new (default) or top (all-time). Page older results with before = the last item's created_utc (sort: new only). | Subreddit | 1 per call | | list_user_posts | A user's own submitted posts as summaries, newest first; same before / after cursor. | User posts | 1 per call | | list_user_comments | A user's own comments, newest first, each paired with its parent post (post_title, post_body, post_author, post_permalink, or post_error). | User comments | 1 per call + 1 per distinct parent post | | search_posts | Keyword search across Reddit or inside one subreddit, returning post summaries. No paging cursor — narrow with subreddit, sort and limit. | Search | 1 per call | | get_user_profile | Karma, account age, trophies, the visible moderator-of list and the public account flags. Never cached (3–15 s). | Profile | 1 per call, released on failure | | get_subreddit_rules | A subreddit's rules in order: short_name, description, applies_to. Never cached (3–15 s). | Rules | 1 per call, released on failure | | get_history | List the durable snapshots this account has already scraped (summaries), optionally by post id. | Post | free | | get_history_latest | Re-fetch the latest stored full post (with comments) for a post id you already scraped. | Post | free | | get_usage | Tier, monthly quota, successful posts used this month, remaining allowance. | any key | free | | get_daily_usage | Request counts per day ({date, count, success}) for the last 1–90 days. | any key | free | | get_account | Profile, shared quota and limits, and every key on the account with its name, permissions, prefix and status. Full keys are never returned. | any key | free |

Permissions

Each API key has a name and a set of permissions chosen when it is created: Post, Subreddit, Rules, User posts, User comments, Profile, Search (a key created without a selection has all of them). A tool called with a key that lacks its permission comes back as a tool error carrying the API's own sentence — "This API key does not have the 'Subreddit' permission. Create a key with it on the API keys page." — plus a line pointing at https://ugcscraper.com/dashboard/keys. No quota is spent on a refused call.

Errors are surfaced exactly as the API states them: one plain sentence, plus one extra sentence of advice for 401 (bad key), 403 (missing permission) and 429 (burst limit or monthly quota).

Setup

1. Get an API key at https://ugcscraper.com/dashboard (starts with rps_live_). The free tier includes 1,000 successful posts per month.
2. Add the server to your MCP client. For Claude Desktop, edit claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "ugc-scraper-reddit": {
      "command": "npx",
      "args": ["-y", "ugc-scraper-reddit-mcp"],
      "env": {
        "UGC_SCRAPER_API_KEY": "rps_live_YOUR_KEY_HERE"
      }
    }
  }
}

3. Restart Claude Desktop. Ask it to "scrape this Reddit thread: " and it will call scrape_reddit_url; ask for "the newest 25 posts in r/webscraping" and it will call list_subreddit_posts.

Environment variables

| Var | Required | Default | Notes | |-----|----------|---------|-------| | UGC_SCRAPER_API_KEY | yes | — | An rps_live_… key from https://ugcscraper.com/dashboard/keys. The server exits at startup if it is missing. Its permissions decide which tools can succeed. | | UGC_SCRAPER_BASE_URL | no | https://api.ugcscraper.com | Point the server at another deployment, e.g. http://localhost:8000 for a local API. Trailing slashes are trimmed. |

Local development

npm install
npm run build      # tsc -> dist/
npm test           # checks package.json and the reported server version agree
UGC_SCRAPER_API_KEY=rps_live_... npm start   # runs the stdio server

To run from source against a local API, set UGC_SCRAPER_BASE_URL=http://localhost:8000.

Use cases

• Pull a Reddit thread straight into a Claude conversation for summarization or sentiment analysis
• Track a subreddit or a user: list the newest posts, then scrape the ones worth reading in full
• Check a subreddit's rules before drafting a post, or look up an account's karma and age
• Re-check scores on a batch of posts you saved earlier, in one call
• Feed structured Reddit data into an LLM/RAG pipeline without leaving your MCP client

Links

• API reference (endpoints, auth, examples): https://ugcscraper.com/reddit-scraper-api
• Platform: https://ugcscraper.com
• Python client: ugcscraper-helper (ugc-scraper-python-helper on GitHub)

License

MIT