Skip to content
Back to search

reddit-mcp-buddy

Clean, LLM-optimized Reddit MCP server. Browse posts, search content, analyze users. No fluff, just Reddit data.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/karanb192/reddit-mcp-buddy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/karanb192/reddit-mcp-buddy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/karanb192--reddit-mcp-buddy/badge.svg)](/listings/karanb192--reddit-mcp-buddy)

HTML

<a href="/listings/karanb192--reddit-mcp-buddy"><img src="/api/listings/karanb192--reddit-mcp-buddy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For Claude Desktop - Desktop Extension (Easiest!)

1. **Download**: [reddit-mcp-buddy.mcpb](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/download/reddit-mcp-buddy.mcpb) 2. **Install**: Open the downloaded file 3. **Done!** Reddit tools are now available in Claude

For Claude Desktop - NPM Method (Alternative)

Add this to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-mcp-buddy"]
    }
  }
}

For Claude Code

Run this command to add the MCP server (user scope):

claude mcp add --transport stdio reddit-mcp-buddy -s user -- npx -y reddit-mcp-buddy

For Other MCP Clients

Use the NPM method: `npx -y reddit-mcp-buddy`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 637 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # <img src="assets/reddit-mcp-buddy-icon-white-background.png" width="48" align="center"/> Reddit MCP Buddy
  2. ### Reddit Browser for Claude Desktop and AI Assistants
  3. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets an AI assistant browse Reddit, search posts, read comment threads, find subreddits, and look at a user's activity through Reddit's own API. Posting and commenting are opt-in. See [Posting](#posting-v120).
  4. > **You need Reddit API credentials that Reddit has already approved.** Reddit is closing the access this server uses, and there is no way to get new credentials for it.
  5. >
  6. > - **2026-10-31:** Reddit stopped accepting new requests for public API access ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)).
  7. > - **2026-11-13:** the date Reddit set for ending RSS feed support ([changelog, October 8, 2026](https://support.reddithelp.com/hc/en-us/articles/54353370049684-Changelog-October-8-2026)). RSS was the only thing this server could read without credentials, so every Reddit tool now needs them.
  8. > - **2027-01-12:** Reddit starts closing API access for apps whose owners have not registered them at [developers.reddit.com/app-registration](https://developers.reddit.com/app-registration) or answered Reddit's outreach ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)).
  9. > - **March 2027:** Reddit ends the remaining public API access ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)).
  10. >
  11. > This project cannot grant API access or register your app for you.
  12. [![npm version](https://img.shields.io/npm/v/reddit-mcp-buddy.svg)](https://www.npmjs.com/package/reddit-mcp-buddy)
  13. [![npm downloads](https://img.shields.io/npm/dm/reddit-mcp-buddy.svg)](https://www.npmjs.com/package/reddit-mcp-buddy)
  14. [![GitHub stars](https://img.shields.io/github/stars/karanb192/reddit-mcp-buddy.svg?style=flat&logo=github&color=brightgreen)](https://github.com/karanb192/reddit-mcp-buddy/stargazers)
  15. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  16. ## See It In Action
  17. ![Reddit MCP Buddy Demo - AirPods Max 2 and Dune Part Three](assets/images/reddit-mcp-buddy-demo-2026.gif)
  18. *Claude checking Reddit's reaction to the Dune Part Three trailer and whether the AirPods Max 2 are worth $549*
  19. ![Reddit MCP Buddy Demo - Analyzing H1B sentiment across subreddits](assets/images/reddit-mcp-buddy.gif)
  20. *Claude analyzing real-time sentiment about H-1B visa changes across r/cscareerquestions and r/india*
  21. ## Table of Contents
  22. - [Quick Start](#quick-start)
  23. - [What you can ask](#what-you-can-ask)
  24. - [Available Tools](#available-tools)
  25. - [NSFW content](#nsfw-content)
  26. - [Authentication](#authentication)
  27. - [Posting (v1.2.0)](#posting-v120)
  28. - [Settings](#settings)
  29. - [Privacy & Data Handling](#privacy--data-handling)
  30. - [Other ways to install](#other-ways-to-install)
  31. - [Troubleshooting](#troubleshooting)
  32. - [Development](#development)
  33. - [Support](#support)
  34. - [Related Resources](#related-resources)
  35. ## Quick Start
  36. You need your approved Reddit app's client ID and secret. [Authentication](#authentication) shows where to find them.
  37. ### Claude Desktop extension
  38. 1. **Download**: [reddit-mcp-buddy.mcpb](https://github.com/karanb192/reddit-mcp-buddy/releases/latest/download/reddit-mcp-buddy.mcpb)
  39. 2. **Install**: Open the downloaded file
  40. 3. **Add credentials**: Enter the client ID and secret in the extension settings
  41. ### Claude Desktop with npm
  42. Add this to your `claude_desktop_config.json`:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "reddit": {
  47. "command": "npx",
  48. "args": ["-y", "reddit-mcp-buddy"],
  49. "env": {
  50. "REDDIT_CLIENT_ID": "your_client_id",
  51. "REDDIT_CLIENT_SECRET": "your_client_secret"
  52. }
  53. }
  54. }
  55. }
  56. ```
  57. ### Claude Code
  58. Run this command to add the MCP server (user scope):
  59. ```bash
  60. claude mcp add --transport stdio reddit-mcp-buddy -s user \
  61. -e REDDIT_CLIENT_ID=your_client_id -e REDDIT_CLIENT_SECRET=your_client_secret \
  62. -- npx -y reddit-mcp-buddy
  63. ```
  64. ### Other MCP clients
  65. Run `npx -y reddit-mcp-buddy` with `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET` set in its environment.
  66. A global install, a build from source and Docker are under [Other ways to install](#other-ways-to-install).
  67. ## What you can ask
  68. | Ask your assistant | What it calls |
  69. |--------------------|---------------|
  70. | "What's trending on Reddit?" | `browse_subreddit` with subreddit `all`, sort `hot` |
  71. | "Show me the top posts in r/technology this week" | `browse_subreddit` with sort `top`, time `week` |
  72. | "What are the top posts about GPT-4 today?" | `search_reddit` with time `day`, sort `top` |
  73. | "Get the comments from this Reddit post" | `get_post_details` with the post's URL |
  74. | "Analyze user spez" | `user_analysis` |
  75. | "Where do people discuss home espresso machines?" | `find_subreddits` with query `home espresso` and the names it thinks fit |
  76. | "Explain Reddit karma" | `reddit_explain` |
  77. | "Post this to r/test" | `subreddit_rules`, then `create_post` after you confirm (opt-in, see [Posting](#posting-v120)) |
  78. What comes back:
  79. - **Reddit's data and nothing else.** No sentiment scores or other invented metrics.
  80. - **Only the fields an assistant needs**, not Reddit's full raw objects.
  81. - **A note when something was left out.** Hidden NSFW items, subreddits that are private, quarantined or banned, and an author or flair filter applied after Reddit's own limit are all reported in the response.
  82. ## Available Tools
  83. ### `browse_subreddit`
  84. Browse posts from any subreddit with sorting options.
  85. ```
  86. - Subreddit:
  87. - "all" - entire Reddit frontpage
  88. - "popular" - trending across Reddit
  89. - Any specific subreddit (e.g., "technology", "programming", "science")
  90. - Sort by: hot, new, top, rising, controversial
  91. - Time range: hour, day, week, month, year, all (for top/controversial sort)
  92. - Include subreddit info: Optional flag for subreddit metadata
  93. - Include NSFW: off by default; posts left out are counted in nsfw_hidden
  94. ```
  95. ### `search_reddit`
  96. Search across Reddit or specific subreddits.
  97. ```
  98. - Query: Your search terms
  99. - Filter by: subreddit, author, time, flair
  100. - Sort by: relevance, hot, top, new, comments
  101. - Include NSFW: off by default. Reddit leaves NSFW posts out before it answers, so a
  102. search inside an NSFW subreddit returns nothing unless this is on
  103. ```
  104. ### `get_post_details`
  105. Get a post and its comments.
  106. ```
  107. - Input:
  108. - Reddit URL (supports multiple formats), OR
  109. - Post ID alone (will auto-detect subreddit, 2 API calls), OR
  110. - Post ID + subreddit (most efficient, 1 API call)
  111. - Supported URL formats:
  112. - reddit.com, www.reddit.com
  113. - old.reddit.com, new.reddit.com
  114. - np.reddit.com (No Participation links)
  115. - m.reddit.com (mobile links)
  116. - redd.it short URLs
  117. - URLs with query params (?utm_source=...) or fragments (#comment)
  118. - Comments: 20 by default, up to 500
  119. - Options: comment sorting, depth, link extraction
  120. ```
  121. ### `user_analysis`
  122. Analyze a Reddit user's profile.
  123. ```
  124. - Username: Any Reddit user
  125. - Returns: karma, posts, comments, active subreddits
  126. ```
  127. ### `find_subreddits`
  128. Find subreddits for a topic, and check subreddit names before using them.
  129. ```
  130. - Query: 2 to 4 keywords, not a sentence (Reddit's subreddit search matches words)
  131. - Candidates: up to 10 subreddit names the assistant thinks fit (optional)
  132. - Include NSFW: off by default; subreddits left out are counted in nsfw_hidden
  133. - Limit: how many Reddit search suggestions to return (default 10, max 50)
  134. - Min subscribers: search suggestions below this are left out (default 1000);
  135. candidates are never filtered by size
  136. - Returns: name, url, title, description, subscribers with an as-of time, NSFW flag, type,
  137. source (assistant or reddit_search), and whether it was confirmed to exist
  138. - Candidates Reddit does not return are listed in not_found; if the name check itself
  139. fails, they come back unchecked instead
  140. - Subreddits that exist but cannot be read (private, quarantined, banned) are listed
  141. in unavailable with the reason
  142. - At most 2 Reddit requests per call
  143. ```
  144. ### `reddit_explain`
  145. Get explanations of Reddit terms. Works offline, with no credentials.
  146. ```
  147. - Terms: karma, cake day, AMA, ELI5, etc.
  148. ```
  149. ### Write tools (opt-in)
  150. `create_post`, `add_comment`, and `subreddit_rules` only appear when you enable posting; read-only installs see exactly the six tools above. Details in [Posting (v1.2.0)](#posting-v120).
  151. ## NSFW content
  152. NSFW posts and subreddits are left out by default. When you ask for them, the assistant can set `include_nsfw` on `browse_subreddit`, `search_reddit` or `find_subreddits` for that one call. To change the rule for the whole server, set `REDDIT_BUDDY_NSFW`:
  153. | Value | What it does |
  154. |-------|--------------|
  155. | `ask` (default) | Hidden unless a call sets `include_nsfw: true` |
  156. | `never` | Always hidden, whatever the assistant sends. `include_nsfw` has no effect, `get_post_details` refuses a post marked NSFW, and `user_analysis` leaves NSFW posts and comments out |
  157. | `always` | Included unless a call sets `include_nsfw: false` |
  158. ```json
  159. "env": {
  160. "REDDIT_CLIENT_ID": "your_client_id",
  161. "REDDIT_CLIENT_SECRET": "your_client_secret",
  162. "REDDIT_BUDDY_NSFW": "never"
  163. }
  164. ```
  165. - In `ask` and `always`, `get_post_details` and `user_analysis` are not filtered: you named the post or the user.
  166. - Any other value is treated as `never` and logged at startup, so a typo cannot open what you meant to lock.
  167. - The server goes by Reddit's own NSFW mark on each post and subreddit, and on the comments in a user's history. It does not inspect content, so something Reddit has marked as not NSFW is shown.
  168. - Reddit puts no NSFW mark on the comments under a post, so the post's mark decides for them: `get_post_details` returns the comments of a post that is not marked NSFW as they are, on `never` too.
  169. - On `never`, anything Reddit has not marked either way is left out as well, and `browse_subreddit` leaves out the subreddit info of an NSFW subreddit.
  170. - Claude Desktop extension users: use the **NSFW content** field in the extension settings. It maps to the same variable.
  171. ## Authentication
  172. Every tool that reads Reddit needs credentials for a Reddit app whose API access Reddit has already approved. Only `reddit_explain`, which works offline, runs without them.
  173. ### Who can use this server
  174. - **You already hold approved Reddit API access:** use your app's credentials below.
  175. - **You do not:** Reddit stopped accepting new requests for public API access on 2026-10-31 ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)), so there is no way to get credentials for this server now. This project cannot grant access, and it does not provide shared API keys or a third-party OAuth service.
  176. - **Keep your access past 2027-01-12:** Reddit starts closing API access on that date for apps whose owners have not registered them at [developers.reddit.com/app-registration](https://developers.reddit.com/app-registration) or answered Reddit's outreach ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)). Registration is done by each app's owner; this project cannot do it for you.
  177. Without credentials, every Reddit tool returns an error that says credentials are needed.
  178. ### Setup Steps
  179. 1. **Open** https://www.reddit.com/prefs/apps and select your approved app.
  180. 2. **Check the app type:** **"script"** supports password-grant authentication, **"web app"** supports OAuth consent with a refresh token (see below), and app-only mode works with both.
  181. 3. **Find your credentials:**
  182. - **Client ID**: The string beneath the app's name and type
  183. - **Client Secret**: The secret string
  184. 4. **Update your Claude Desktop config:**
  185. ```json
  186. {
  187. "mcpServers": {
  188. "reddit": {
  189. "command": "npx",
  190. "args": ["-y", "reddit-mcp-buddy"],
  191. "env": {
  192. "REDDIT_CLIENT_ID": "your_client_id",
  193. "REDDIT_CLIENT_SECRET": "your_client_secret",
  194. "REDDIT_USERNAME": "your_username",
  195. "REDDIT_PASSWORD": "your_password"
  196. }
  197. }
  198. }
  199. }
  200. ```
  201. ### Web apps with OAuth consent
  202. An approved web app can authenticate a user without their Reddit password. `--oauth` runs Reddit's [authorization-code flow](https://github.com/reddit-archive/reddit/wiki/OAuth2#authorization) once and prints a refresh token.
  203. 1. **Register the redirect URI.** On [Reddit app preferences](https://www.reddit.com/prefs/apps), the web app's redirect URI must be a loopback address with a port, such as `http://localhost:8080`.
  204. 2. **Run the consent command** on the machine where your browser is signed in to Reddit:
  205. ```bash
  206. npx -y reddit-mcp-buddy --oauth
  207. ```
  208. It prompts for the web app's client ID and secret, or reads `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET` from the environment. It requests `identity`, `read`, and `history`, which the read-only tools need. Add `--write` to also request `submit` and `flair` for [posting](#posting-v120). Pass `--redirect-uri http://localhost:<port>` if you registered a different port.
  209. 3. **Open the printed link and click Allow.** Reddit redirects back to a temporary local server that only listens on your machine. It checks the random `state` value, exchanges the one-time code, and confirms the account with `/api/v1/me`. It waits up to 5 minutes and never posts.
  210. 4. **Copy the token into your config.** It prints `REDDIT_REFRESH_TOKEN=...`. To keep it off the screen, add `--out ~/reddit-token.env`, a path outside any repository. If that file already exists, the command stops before asking for consent. If writing fails after consent, it prints the token instead. On macOS and Linux the file is readable only by you.
  211. Set these variables in the server's environment:
  212. ```json
  213. {
  214. "REDDIT_CLIENT_ID": "your_client_id",
  215. "REDDIT_CLIENT_SECRET": "your_client_secret",
  216. "REDDIT_REFRESH_TOKEN": "your_refresh_token"
  217. }
  218. ```
  219. Leave `REDDIT_PASSWORD` unset when using a refresh token. Setting both is rejected at startup. The server exchanges the refresh token for access tokens as needed and does not write environment credentials to `auth.json`. Refresh tokens loaded from that file are not used; configure this mode through the environment.
  220. Treat a refresh token like a password. Keep it outside version control and revoke access in [Reddit app preferences](https://www.reddit.com/prefs/apps) when it is no longer needed. OAuth consent does not grant Reddit API approval or extend the approved use case.
  221. ### Modes and local request caps
  222. The server enforces these caps itself. They are not Reddit API quotas or guaranteed throughput.
  223. | Mode | Credentials | Local cap |
  224. |------|-------------|-----------|
  225. | **App-only** | Client ID + secret | 60 requests/minute |
  226. | **User** | Client ID + secret, plus a refresh token or username and password | 100 requests/minute |
  227. - App-only mode uses the OAuth2 client credentials grant and works with both script and web apps.
  228. - User mode uses a refresh token for an authorized web app, or the password grant for a script app.
  229. - A refresh token carries the scopes granted during consent. Missing scopes can prevent individual tools from working.
  230. - User mode raises this server's local cap. It does not grant a larger quota from Reddit.
  231. ## Posting (v1.2.0)
  232. Since v1.2.0 the server can post for you. Three tools, all opt-in:
  233. - **`create_post`** - Submit a text or link post to one subreddit. Checks mechanical rules (title limits, flair required, link vs text allowed) and supports `validate_only: true` as a dry run. Confirmation depends on the client's capabilities as described below.
  234. - **`add_comment`** - Comment on a post or reply to a specific comment (by id or URL), with the same confirmation flow.
  235. - **`subreddit_rules`** - Read-only. Fetches a sub's rules, posting requirements, capability flags, and flair choices in one cached call, so drafts fit the sub before anything is submitted.
  236. The intended workflow: `subreddit_rules` first, then `create_post` with `validate_only: true`, review the full draft and options with the user, then submit the identical payload.
  237. ### Enabling posting
  238. Add `REDDIT_BUDDY_WRITE` next to your existing credentials:
  239. ```json
  240. {
  241. "mcpServers": {
  242. "reddit": {
  243. "command": "npx",
  244. "args": ["-y", "reddit-mcp-buddy"],
  245. "env": {
  246. "REDDIT_CLIENT_ID": "your_client_id",
  247. "REDDIT_CLIENT_SECRET": "your_client_secret",
  248. "REDDIT_USERNAME": "your_username",
  249. "REDDIT_PASSWORD": "your_password",
  250. "REDDIT_BUDDY_WRITE": "true"
  251. }
  252. }
  253. }
  254. }
  255. ```
  256. Claude Desktop extension users: flip the **Enable posting tools** toggle in the extension settings instead. It maps to the same `REDDIT_BUDDY_WRITE` variable.
  257. Alternatively, replace `REDDIT_PASSWORD` with `REDDIT_REFRESH_TOKEN` from the [web-app consent flow](#web-apps-with-oauth-consent); `npx -y reddit-mcp-buddy --oauth --write` requests the posting scopes. Posting requires the granted scopes `identity`, `read`, `submit`, and `flair`. Add `history` if you also use `user_analysis`. `REDDIT_USERNAME` is optional with a refresh token; when provided, it must match the account returned by Reddit.
  258. Credentials must come from environment variables (or extension config fields, which become environment variables). The interactive `--auth` file setup does not enable posting. Startup verifies the account through Reddit and checks granted scopes. If any requirement is missing, the server logs the reason and keeps posting tools disabled.
  259. ### The safety model, in plain words
  260. Posting uses your account. The server enforces registration, rate limits, and duplicate checks; human approval also depends on the client:
  261. - **Off by default.** Without `REDDIT_BUDDY_WRITE`, the write tools do not exist: read-only installs see only the 6 read tools, and pay zero extra context.
  262. - **stdio only.** The HTTP transport has no authentication, so write tools refuse to register there. No process on your machine or network can turn the HTTP endpoint into a posting proxy.
  263. - **Confirmation depends on the client.** Clients supporting [MCP elicitation](https://modelcontextprotocol.io/specification/latest) get a confirmation prompt with the target, account, content preview, full content length, and post options. The prompt requires an explicit acceptance. Previews can be truncated, so review the full draft in your client first. Without elicitation, the server requires a preview or successful dry run followed by the identical payload within 15 minutes. It cannot verify that a human approved that repeat: approval depends on the client's tool prompt and the model following instructions. Only enable posting in a client whose approval behavior you trust.
  264. - **Hourly caps you cannot raise.** At most 5 posts/hour, 30 comments/hour, and 15 seconds between writes, enforced in the server. Environment variables can tighten these, never loosen them. Honest limit: the caps live in the server process (a restart resets the hour, parallel sessions have separate caps, and a fork of this open-source code can remove them). They exist to make casual abuse pointless, not to stop a determined operator.
  265. - **Duplicate suppression.** Retrying an identical submit within 15 minutes returns the original post instead of posting twice, including the same content re-drafted for the same sub. Posting the same content to a different subreddit is allowed, with a warning naming the earlier post.
  266. - **Verified after submit.** Reddit happily returns "success" for posts AutoModerator removes seconds later. The server re-checks after submitting and reports `status: "filtered"` with a warning when that happens, instead of telling you it went live.
  267. - **Conspicuous logging.** Every allowed write is logged to stderr with the kind, the target (subreddit when known), and the acting user.
  268. ### Know the trade-off before enabling
  269. Reddit's password grant returns a token with **full account scope**. An OAuth refresh token carries the permissions granted during consent. These permissions apply across the account, not just one subreddit. With posting off, the server uses the credentials for reads; enabling posting lets it submit posts and comments. Keep passwords and refresh tokens out of version control and off shared machines.
  270. Also worth knowing: Reddit applies its own account-level posting throttles on top of everything above, based on account age and karma. If Reddit says "try again in N minutes", the server surfaces the wait instead of hammering.
  271. ## Settings
  272. ### Environment variables
  273. #### Authentication Variables
  274. | Variable | Description | Required |
  275. |----------|-------------|----------|
  276. | `REDDIT_CLIENT_ID` | Reddit app client ID | Yes |
  277. | `REDDIT_CLIENT_SECRET` | Reddit app secret | Yes |
  278. | `REDDIT_USERNAME` | Reddit account username, with the password for a script app | No |
  279. | `REDDIT_PASSWORD` | Reddit account password; leave unset when using a refresh token | No |
  280. | `REDDIT_REFRESH_TOKEN` | OAuth refresh token for a web app | No |
  281. | `REDDIT_USER_AGENT` | Custom user agent string | No |
  282. Which credentials select which mode, and the local cap for each, are under [Modes and local request caps](#modes-and-local-request-caps).
  283. #### Server Configuration
  284. | Variable | Description | Default |
  285. |----------|-------------|---------|
  286. | `REDDIT_BUDDY_HTTP` | Run as HTTP server instead of stdio | `false` |
  287. | `REDDIT_BUDDY_PORT` | HTTP server port (when HTTP=true) | `3000` |
  288. | `REDDIT_BUDDY_HOST` | Interface the HTTP server binds to | `127.0.0.1` |
  289. | `REDDIT_BUDDY_ALLOWED_ORIGINS` | Comma-separated browser origins allowed to call the HTTP endpoint | none |
  290. | `REDDIT_BUDDY_ALLOWED_HOSTS` | Comma-separated `host:port` values accepted in the Host header (DNS-rebinding protection) | loopback values when bound to localhost |
  291. | `REDDIT_BUDDY_NO_CACHE` | Disable caching (always fetch fresh) | `false` |
  292. | `REDDIT_BUDDY_NSFW` | [NSFW content](#nsfw-content): `ask` (hidden unless a call asks), `never` (always hidden) or `always` (included by default) | `ask` |
  293. #### Posting (v1.2.0)
  294. | Variable | Description | Default |
  295. |----------|-------------|---------|
  296. | `REDDIT_BUDDY_WRITE` | Register the [posting tools](#posting-v120); requires env user credentials, verified identity and scopes, and stdio | `false` |
  297. | `REDDIT_BUDDY_MAX_POSTS_PER_HOUR` | Posts per hour; only values from 1 to 4 are honored (0 and invalid values are ignored) | `5` |
  298. | `REDDIT_BUDDY_MAX_COMMENTS_PER_HOUR` | Comments per hour; only values from 1 to 29 are honored (0 and invalid values are ignored) | `30` |
  299. | `REDDIT_BUDDY_MIN_WRITE_INTERVAL_S` | Seconds between writes; only values ABOVE 15 are honored | `15` |
  300. The three rate-floor variables can only tighten the built-in caps. Setting them looser than the defaults does nothing, on purpose, and 0 does not mean "pause posting": it falls back to the default cap.
  301. ### HTTP mode
  302. The server runs over stdio by default. To run it as a local HTTP server, for Postman MCP or direct API calls:
  303. ```bash
  304. # Run in HTTP mode on port 3000
  305. npx -y reddit-mcp-buddy --http
  306. # Or with custom port
  307. REDDIT_BUDDY_PORT=8080 npx -y reddit-mcp-buddy --http
  308. ```
  309. > **HTTP mode has no authentication.** It binds to localhost so only your machine can reach it, and rejects Host headers outside the loopback set. Setting `REDDIT_BUDDY_HOST=0.0.0.0` exposes it to your whole network - only do that on a trusted network (e.g. inside Docker, which sets it deliberately). On a non-loopback bind the Host check is off by default, since clients legitimately arrive with a container IP or service name; set `REDDIT_BUDDY_ALLOWED_HOSTS` to restrict it. Browser requests are rejected unless their origin is listed in `REDDIT_BUDDY_ALLOWED_ORIGINS`; non-browser clients like Postman are unaffected.
  310. ### Caching
  311. Reddit's responses are cached in memory to cut repeat requests.
  312. | Content | Cached for |
  313. |---------|------------|
  314. | Subreddit listings | 5 minutes |
  315. | Post details | 10 minutes |
  316. | Search results | 10 minutes |
  317. | User profiles | 15 minutes |
  318. - The cache is capped at 50MB and evicts the least-used entries first.
  319. - Everything is cleared when the server stops.
  320. - Set `REDDIT_BUDDY_NO_CACHE=true` to turn it off.
  321. ### HTTP and HTTPS Proxies
  322. On Node 22.21.0+ in the 22.x line, or Node 24 and newer, enable Node's built-in proxy support before starting the server. The project's Node 26 Docker image supports this. Check `node --version` first: unsupported versions can ignore these settings and connect directly. Node currently marks this feature as under active development.
  323. ```json
  324. {
  325. "mcpServers": {
  326. "reddit": {
  327. "command": "npx",
  328. "args": ["-y", "reddit-mcp-buddy"],
  329. "env": {
  330. "NODE_USE_ENV_PROXY": "1",
  331. "HTTP_PROXY": "http://proxy.example.com:8080",
  332. "HTTPS_PROXY": "http://proxy.example.com:8080",
  333. "NO_PROXY": "localhost,127.0.0.1"
  334. }
  335. }
  336. }
  337. }
  338. ```
  339. `HTTP_PROXY` routes HTTP requests; `HTTPS_PROXY` routes HTTPS requests, including Reddit API calls. `NO_PROXY` excludes matching hosts. Export these variables in your shell for CLI use, or pass them with Docker's `-e` options. Set them in the process environment before startup; the server does not load a project `.env` file automatically.
  340. Inside Docker, `localhost` refers to the container. On Docker Desktop, use `host.docker.internal` to reach a proxy running on the host.
  341. Proxy authentication can be included in the proxy URL as `http://username:password@proxy.example.com:8080`. Treat that value as a credential and redact it from shared logs and configuration. For a network that uses a private certificate authority, use `NODE_EXTRA_CA_CERTS` with your organization's PEM certificate file instead of disabling TLS verification.
  342. See [Node's proxy and certificate configuration guide](https://nodejs.org/learn/http/enterprise-network-configuration). Proxy support routes network traffic; it does not grant Reddit API approval or bypass Reddit's access rules.
  343. ## Privacy & Data Handling
  344. Reddit MCP Buddy is designed with privacy and transparency in mind. Here's how your data is handled:
  345. ### Data Collection
  346. - **Reddit API Data**: The server fetches public Reddit content (posts, comments, user profiles) through Reddit's official API
  347. - **No Tracking**: We don't collect, store, or transmit any analytics, telemetry, or usage data
  348. - **No Third Parties**: All data flows directly between your machine, Reddit's API, and your AI assistant
  349. ### Local Storage
  350. - **Authentication Credentials** (optional):
  351. - Stored locally in `~/.reddit-mcp-buddy/auth.json` when using `--auth` CLI setup
  352. - Passwords are **never** written to disk - only used in-memory for OAuth token exchange
  353. - Environment variables (recommended for Claude Desktop) are never persisted by this server
  354. - **Cache Data**:
  355. - Reddit API responses are cached in memory only and cleared when the server stops (see [Caching](#caching))
  356. ### Data Transmission
  357. - **Reddit API Only**: Your credentials are only sent to Reddit's official OAuth endpoints (`https://oauth.reddit.com` and `https://www.reddit.com`)
  358. - **No External Services**: No data is sent to any other external services, analytics platforms, or third parties
  359. - **Local Processing**: All data processing happens locally on your machine
  360. ### Security Notes
  361. - **Read-Only by Default**: Posting requires explicit opt-in. Review the [client-dependent confirmation flow](#the-safety-model-in-plain-words) before enabling it.
  362. - **Credential Safety**:
  363. - OAuth tokens are refreshed automatically and kept in memory; only `--auth` CLI setups also cache the token in `~/.reddit-mcp-buddy/auth.json` (file mode 600)
  364. - Client secrets are treated as sensitive and never logged
  365. - Use environment variables in Claude Desktop config for maximum security
  366. - **Open Source**: Full source code is available at https://github.com/karanb192/reddit-mcp-buddy for security auditing
  367. ### GDPR & Privacy Compliance
  368. - **No Personal Data Collection**: We don't collect or process any personal data beyond what's necessary to authenticate with Reddit's API
  369. - **User Control**: You control all credentials and can delete `~/.reddit-mcp-buddy/auth.json` at any time
  370. - **Right to Erasure**: Simply delete the auth file or uninstall the server to remove all local data
  371. ### Questions or Concerns?
  372. If you have any privacy questions or concerns, please [open an issue](https://github.com/karanb192/reddit-mcp-buddy/issues) on GitHub.
  373. ## Other ways to install
  374. ### Global Install
  375. ```bash
  376. npm install -g reddit-mcp-buddy
  377. reddit-buddy --http # For testing
  378. ```
  379. ### From Source
  380. ```bash
  381. git clone https://github.com/karanb192/reddit-mcp-buddy.git
  382. cd reddit-mcp-buddy
  383. npm install
  384. npm run build
  385. npm link
  386. ```
  387. ### Using Docker
  388. The Docker image and CI workflows use Node.js 26. To build and run the image:
  389. ```bash
  390. git clone https://github.com/karanb192/reddit-mcp-buddy.git
  391. cd reddit-mcp-buddy
  392. docker build --pull -t reddit-mcp-buddy .
  393. docker run -it -e REDDIT_CLIENT_ID=your_client_id -e REDDIT_CLIENT_SECRET=your_client_secret reddit-mcp-buddy
  394. ```
  395. Run the container smoke test with Docker, curl, and jq installed:
  396. ```bash
  397. bash tests/test-docker.sh reddit-mcp-buddy
  398. ```
  399. The test checks container health, MCP initialization, tool discovery, and shutdown without Reddit credentials.
  400. ### Build the Claude Desktop extension from source
  401. The pre-built extension is in [Quick Start](#quick-start). To build it yourself:
  402. ```bash
  403. git clone https://github.com/karanb192/reddit-mcp-buddy.git
  404. cd reddit-mcp-buddy
  405. ./scripts/build-mcpb.sh
  406. ```
  407. ## Troubleshooting
  408. ### Common Issues
  409. **"Reddit ended logged-out RSS access on 2026-11-13"**
  410. - The server has no credentials, and it reads nothing from Reddit without them. Reddit set 2026-11-13 as the end of its RSS feeds ([changelog](https://support.reddithelp.com/hc/en-us/articles/54353370049684-Changelog-October-8-2026)), which were the only logged-out route. The subreddit, post, or user you asked for is not the problem
  411. - Add your approved app's credentials (see [Authentication](#authentication)). Reddit stopped accepting new API access requests on 2026-10-31, so this only helps people who already hold access
  412. **"Cannot create an app" or "API approval required"**
  413. - Reddit stopped accepting new requests for public API access on 2026-10-31 ([migration post](https://www.reddit.com/r/redditdev/comments/1wubcvf/moving_data_api_apps_to_the_developer_platform/)); this project cannot approve an app or remove Reddit's restrictions
  414. - Use credentials only for an app and use case Reddit has approved
  415. **"Command not found" error**
  416. ```bash
  417. # Ensure npm is installed
  418. node --version
  419. npm --version
  420. # Try the full global-bin path
  421. $(npm prefix -g)/bin/reddit-mcp-buddy
  422. ```
  423. **Rate limit errors, or fewer requests per minute than the cap**
  424. - The caps under [Modes and local request caps](#modes-and-local-request-caps) are this server's own. Reddit applies its own API limits on top, and user credentials do not raise them
  425. - The server retries transient failures, but sustained throttling can still fail
  426. - If an error says `Retry in Ns`, wait that long before retrying. The server returns long upstream waits immediately instead of sleeping through the client's request timeout.
  427. **Write tools don't show up**
  428. - All of these must hold: `REDDIT_BUDDY_WRITE=true`, client credentials plus a refresh token or username/password via environment variables, stdio transport, a verified user identity, and granted `identity`/`read`/`submit`/`flair` scopes
  429. - The startup log (stderr) names exactly which condition failed
  430. - `--auth` file setups cannot write: the password is never saved, so restarts fall back to app-only tokens. Move credentials into your MCP client config's `env` block
  431. - HTTP mode never registers write tools, by design (the HTTP endpoint has no authentication)
  432. **"Subreddit not found"**
  433. - Ask the assistant to check the name with `find_subreddits`. It lists names Reddit does not know in `not_found` and names that are private, quarantined or banned in `unavailable`
  434. - Subreddit names are not case-sensitive
  435. **Connection issues**
  436. - Reddit may be down (check https://www.redditstatus.com)
  437. - Firewall blocking requests
  438. - Try restarting the MCP server
  439. ## Development
  440. ```bash
  441. # Install dependencies
  442. npm install
  443. # Run in development
  444. npm run dev
  445. # Build
  446. npm run build
  447. # Run tests
  448. npm test # Unit tests
  449. npm run test:integration # Integration tests
  450. npm run test:all # All tests
  451. # Type check
  452. npm run typecheck
  453. ```
  454. Rate-limit checks, local credential setup with `--auth`, and the private sandbox posting test are in [CONTRIBUTING.md](CONTRIBUTING.md#-testing).
  455. ### Requirements
  456. - Node.js >= 20.0.0
  457. - npm
  458. - TypeScript 5.5+
  459. ## Contributing
  460. PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  461. We keep things simple:
  462. - No fake analytics
  463. - Clean, typed code
  464. - Clear documentation
  465. - Fast responses
  466. ## Support
  467. - 🐛 [Report bugs](https://github.com/karanb192/reddit-mcp-buddy/issues)
  468. - 💡 [Request features](https://github.com/karanb192/reddit-mcp-buddy/issues)
  469. - ⭐ [Star on GitHub](https://github.com/karanb192/reddit-mcp-buddy)
  470. ## Related Resources
  471. ### Official MCP Resources
  472. - **[MCP Registry](https://registry.modelcontextprotocol.io)** - Official registry of MCP servers
  473. - **[MCP Specification](https://modelcontextprotocol.io/specification/latest)** - Official Model Context Protocol specification
  474. - **[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - SDK used to build this server
  475. - **[MCP Servers Repository](https://github.com/modelcontextprotocol/servers)** - Collection of official MCP server implementations
  476. - **[Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)** - Community-curated list of MCP servers
  477. ### Where to Find This Server
  478. - **[MCP Registry API Link](https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy)** - Direct API query for this server
  479. - **[MCP Registry Search](https://registry.modelcontextprotocol.io)** - Search for "reddit" to find all versions
  480. - **[NPM Package](https://www.npmjs.com/package/reddit-mcp-buddy)** - Install via npm/npx
  481. - **[GitHub Repository](https://github.com/karanb192/reddit-mcp-buddy)** - Source code and issues
  482. ## License
  483. MIT - Use it however you want!
  484. ---
  485. Made with ❤️ for the MCP community. No venture capital, no tracking, just a good MCP server.
  486. Built by [Karan Bansal](https://karanbansal.in) (Head of AI at ArmorCode). I write about Claude Code, MCP, and production agentic AI at [karanbansal.in/blog](https://karanbansal.in/blog/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.