RedditAPIs

redditapis-mcp

[npm version] [npm downloads] [license]

redditapis-mcp is the official MCP server for RedditAPIs, built for developers and AI agents that need live Reddit data in Claude, Cursor, Windsurf, VS Code or any MCP client, with no Reddit developer app. Your agent can search posts and comments, read subreddit feeds and rules, expand comment trees, look up users and communities, and set up monitors that send new matching posts to your webhook. Reads cost $0.0015 per call (or a monthly read plan from $19 for 30,000 reads), every account gets 1,000 free reads a month, and new accounts get $0.50 of free credit with no card. Connect your Reddit account once to comment, post, vote and DM as you. Every tool maps to one endpoint at api.redditapis.com.

Install: npx -y redditapis-mcp@latest with REDDITAPIS_KEY from https://www.redditapis.com

Hosted, sign in instead of pasting a key (Claude Code): claude mcp add --transport http reddit https://api.redditapis.com/mcp (carries every tool except the 5 that read your own account)

Website: https://www.redditapis.com/mcp

Quick start

No install needed. Run with npx. You need one thing: an API key from redditapis.com. Reads work with just that key, so there is no account login or session step to set up. Monitor/webhook management additionally requires an active monitoring plan (monitoring has no free tier).

Setup

Claude Desktop

Edit claude_desktop_config.json (Settings > Developer > Edit Config):

{  "mcpServers": {    "reddit": {      "command": "npx",      "args": ["-y", "redditapis-mcp@latest"],      "env": { "REDDITAPIS_KEY": "YOUR_API_KEY" }    }  }}

Restart Claude Desktop. The reddit_* tools appear in the tool picker.

Claude Code

claude mcp add reddit --env REDDITAPIS_KEY=YOUR_API_KEY -- npx -y redditapis-mcp@latest

Cursor

~/.cursor/mcp.json (or Settings > MCP > Add New Server):

{  "mcpServers": {    "reddit": {      "command": "npx",      "args": ["-y", "redditapis-mcp@latest"],      "env": { "REDDITAPIS_KEY": "YOUR_API_KEY" }    }  }}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{  "mcpServers": {    "reddit": {      "command": "npx",      "args": ["-y", "redditapis-mcp@latest"],      "env": { "REDDITAPIS_KEY": "YOUR_API_KEY" }    }  }}

VS Code (Copilot / agent mode)

.vscode/mcp.json in your workspace, or the user-level MCP settings:

{  "servers": {    "reddit": {      "type": "stdio",      "command": "npx",      "args": ["-y", "redditapis-mcp@latest"],      "env": { "REDDITAPIS_KEY": "YOUR_API_KEY" }    }  }}

Configuration

Authentication is a Bearer token: the server sends Authorization: Bearer <REDDITAPIS_KEY> on every request.

Tools

61 tools and 3 playbook resources: 33 Reddit reads, 10 Reddit account tools (connect, status, disconnect, comment, submit, vote, DM, and schedule, list or cancel a post or comment for later), 11 monitor/webhook management tools, reddit_set_watch (one call that stands up a whole watch), reddit_explain (where the rows you are holding came from), 3 feedback tools, and 2 account tools (reddit_account_me, which is also where the credit balance lives, and reddit_account_payments, the top-up history). Reddit writes (commenting, posting, voting, DMs) act as YOUR Reddit account and only after you connect it with reddit_connect; each is marked as a write so your client asks before it runs. Monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself, and the feedback tools send a report to the redditapis.com team, never to Reddit. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below). The feedback tools are free and need only your key.

A few conventions across the catalog:

• Subreddit names go in without the r/ prefix, and usernames without the u/ prefix. reddit_subreddit_posts takes its community as subreddit; the /sub/{name}/... tools take it as name.
• Listing and search tools return an after cursor. Pass it back as after to fetch the next page, exactly as it was returned. limit accepts 1 to 100 (the API clamps out-of-range values).
• When after comes back null there is no next page to ask for. That does not always mean you have every item: Reddit often stops serving a busy listing long before it runs out. The final response also carries listing_status, which reads complete, truncated or unknown. Only complete means nothing is missing. Treat the other two as a partial answer and widen across sorts, timeframes or search terms rather than paging deeper.
• t (hour, day, week, month, year, all) sets the time window; on subreddit listings it applies to the top and controversial sorts, and on search it bounds the whole result set.

Search and discovery

Subreddits

Posts and comments

Users

Community browse (no keyword)

Monitoring: manage your own monitors and webhooks

Monitors watch named subreddits or all of Reddit, for posts or comments (kind). Every account holds a free entitlement of one all-of-Reddit post watch at a 60s cadence; naming a subreddit, matching comments, a faster cadence and any further watch need a paid plan. Registering a webhook does not need a paid plan, because the free watch delivers to one exactly like a paid watch does. Reading your own list, health and deliveries never needs a plan.

reddit_monitor_list returns a slots object that states this account's capabilities outright: used, total, tier, is_free, cadence_s (the tier's cadence floor), sitewide_slots, distinct_subreddits_used, distinct_subreddits_total, comments_allowed, scoped_allowed and sitewide_allowed. reddit_set_watch reads those flags before it builds anything.

reddit_set_watch refuses rather than guesses

Every character of your description has to be claimed by exactly one thing: a subreddit, a quoted phrase, a keyword, an exclusion, a score clause, a delivery clause, or a word that carries no filter content. Anything left over means the compiler did not understand the whole sentence, and it returns no filter at all rather than a monitor built from the half it did understand.

This matters because a wrong watch is invisible: you get a monitor id, a green test delivery, and then either silence forever or a firehose. A refusal that names the words it could not place is recoverable in seconds; a monitor whose keyword is also its exclusion is not noticed for a week. If a description is refused, quote the exact phrase to watch for, write subreddits as r/Name, or build the filter directly with reddit_monitor_add.

Playbooks: three recipes, served as MCP resources

Three reusable recipes ship as MCP resources rather than tools, because the protocol makes resources application-driven: a host shows them in a picker or a search box and reads one only when it is asked for by URI. Nothing is prefetched and nothing is injected.

Each is a short markdown document built only from calls this package already exposes, so a recipe cannot point at something unbuilt. A test checks every tool each playbook names against the live catalog.

The bodies are documentation and name the calls they are recipes for, which is the point of them. That is a deliberate difference from tool descriptions, which a client fetches at connect time and nobody chose: those state product facts only and a gate enforces it. A resource is read only when something asks for its URI, so it is a document you opened, not an injection. The bodies are still checked for hidden or encoded text, for any link off our own hosts, and for adversarial steering (overriding your instructions, concealment, exfiltration, or spending your credits in a loop), each with a planted-defect control.

// resources/list, then{ "method": "resources/read", "params": { "uri": "playbook://subreddit-audit" } }

Your Reddit account: connect once, then comment, post, vote, DM and schedule

reddit_connect stores your Reddit session on our side, encrypted (AES-256-GCM, the key held only by the API), against this API key's account, after checking it with Reddit. Every write after that sends no cookies, so they never sit in your agent's tool calls or transcript. Each write acts publicly as you, so it is marked as a write and your client asks before it runs. Connecting, status and disconnecting are free.

Feedback: tell the team what broke, after you review the draft

Modelled on Claude Code's own feedback tool. When a call fails in a way that is not your key, credits or a rate limit, when you ask for something no tool covers, or when a result is plainly wrong, the model can draft a report into a local queue (~/.redditapis/feedback-queue.json, at most 10 drafts, override the directory with REDDITAPIS_FEEDBACK_DIR). Nothing is sent until you ask to review the queue and name the drafts to send. Each report carries the last failing call's endpoint, status and request id, your client name and this package's version, so the team can act on it without a follow-up. Use reddit_feedback_get with the returned server id to see whether it was triaged, shipped or declined. Both tools are free.

Usage examples

Research a topic across Reddit

"What are people saying about the Rust borrow checker this month?"

The agent calls reddit_search with:

q: "borrow checker"sort: "relevance"t: "month"sort_type: "score"

Read a community's top posts of the week

"Show me the top posts in r/programming this week."

The agent calls reddit_subreddit_top with:

name: "programming"t: "week"

To page further, pass the after cursor from the response back on the next call: { name: "programming", t: "week", after: "<after from response>" }.

Find who is talking about a product

"Which redditors are recommending mechanical keyboards, and what do they say?"

The agent calls reddit_deep_comment_search with:

q: "mechanical keyboard"group_by: "author"sort: "relevance"

Research mode returns the distinct people who mentioned the query, ranked by how many of their comments matched, each with their top comment and the subreddits they matched in.

Vet a subreddit, then read a thread

"Find a discussion about API rate limiting in r/webdev, check the sub's rules, and read the full thread."

The agent calls reddit_search scoped to the community:

q: "rate limiting"subreddit: "webdev"sort: "relevance"t: "year"

Then reddit_subreddit_rules with { name: "webdev" }, and finally reddit_post_comments with the permalink from a search result, for example { permalink: "/r/webdev/comments/abc123/some_title/" }, to pull the post and its comment tree.

Set up brand monitoring and check what came in

"Watch r/SaaS and r/startups for mentions of my product, send matches to my Slack, and show me what's come in so far."

The agent calls reddit_monitor_webhook_create with:

url: "https://hooks.slack.com/services/..."kind: "slack"

Then reddit_monitor_add with:

subreddit: ["SaaS", "startups"]q: "my product name"

Later, reddit_monitor_deliveries with { id: "<monitor id from the add response>" } returns the actual matching posts sent so far, or reddit_monitor_health for just the counts.

No session needed for reads; monitor/webhook writes need an active plan

Reads need nothing but your API key -- no account linking, login, or cookie step. Reddit write actions (commenting, posting, voting, sending DMs) need one extra step: reddit_connect stores your Reddit session on our side, encrypted, so later calls carry no cookies. Until you connect, no tool can post, vote or DM as you, and reddit_disconnect deletes the stored session at any time. Monitor/webhook management tools are a different kind of write: they configure your OWN redditapis.com account (an alerting subscription) and require an active monitoring plan for anything that creates or changes state (reddit_monitor_add/update/remove, reddit_monitor_webhook_create/test/delete); reading your own list, health, or delivery history never does.

Troubleshooting

HTTP 401 (invalid or missing API key) Check that REDDITAPIS_KEY is set correctly in your MCP client config and matches the key from redditapis.com.

HTTP 402 (insufficient credits) Top up your account at redditapis.com. For a monitor/webhook write specifically, a 402 body of subscription_required means there is no active monitoring plan (monitoring has no free tier); monitor_slots_exhausted means the plan's monitor slot limit is already in use -- reddit_monitor_list's slots field shows used vs total.

HTTP 403 (access forbidden) The subreddit or user may be private, banned, or quarantined, or your plan may not include this endpoint.

HTTP 404 (not found) The subreddit, post id, user, or permalink may be wrong or the content may have been deleted or removed.

HTTP 429 (rate limited) Wait a few seconds and retry, or reduce request frequency. For bulk work, space out calls and raise REDDITAPIS_TIMEOUT_MS.

HTTP 408 or HTTP 503 with upstream_timeout The read did not finish in time and was not billed (a 503 means the API's own read budget ran out). The server already retried once after retry_after (or the Retry-After header), when that retry can still finish inside REDDITAPIS_TIMEOUT_MS; call the tool again shortly. A 503 upstream_unavailable on a read gets the same one retry.

Request failed: timed out after 30000ms The default timeout is 30 seconds. For large reddit_deep_comment_search or paginated fetches, set REDDITAPIS_TIMEOUT_MS higher (for example 60000).

Tools do not appear in Claude / Cursor Ensure npx is on your PATH and Node.js 18+ is installed (node --version). Check your MCP client logs for startup errors.

Development

npm installnpm run check   # syntax-check both source filesnpm test        # unit-test the tool catalog + query/path builders (no network)npm start       # run the stdio server (needs REDDITAPIS_KEY)

Links

• Site and API keys: redditapis.com
• REST API base URL (call it directly, without MCP): https://api.redditapis.com

FAQ

Do I need a Reddit developer app? No. One RedditAPIs key covers every read, with no Reddit developer app to register.

What does it cost? $0.0015 per read pay as you go, or a monthly read plan from $19 for 30,000 reads; every account gets 1,000 free reads a month, plus $0.50 of free credit at signup and no card. Monitors need a monitoring plan, which has no free tier.

Can it post, comment or vote? Yes, after you connect your Reddit account once with reddit_connect (your session is stored encrypted on our side and never travels in later calls). reddit_comment, reddit_submit, reddit_vote and reddit_dm then act as that account, and each is marked as a write so your client asks before it runs. reddit_disconnect deletes the stored session. Of the other tools, the 11 monitor/webhook tools manage your OWN redditapis.com monitors and webhooks (a write, but never a write to Reddit itself), reddit_set_watch sets up a whole watch in one call, reddit_explain says where the rows you hold came from, the 3 feedback tools send or read a report to the redditapis.com team, and reddit_account_me and reddit_account_payments read your own balance, plan and top-up history.

Which clients are supported? Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.

Does it store my key or data? No. The server holds no state and forwards your API key on each call.

License

MIT