reddit-mcp-server 1.5.3 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +59 -53
  2. package/dist/bin.js +2 -2
  3. package/dist/index.js +157 -55
  4. package/dist/index.js.map +1 -1
  5. package/package.json +3 -2
package/README.md CHANGED
@@ -26,8 +26,8 @@ A Model Context Protocol (MCP) server for interacting with Reddit - fetch posts,
26
26
  | Search Reddit | :white_check_mark: | :white_check_mark: |
27
27
  | User Analysis | :white_check_mark: | :white_check_mark: |
28
28
  | Post Comments | :white_check_mark: | :white_check_mark: |
29
- | Zero-Setup Anonymous Mode | :white_check_mark: | :white_check_mark: |
30
- | Three-Tier Auth (10/60/100 rpm) | :white_check_mark: | :white_check_mark: |
29
+ | OAuth Auth (60-100 rpm) | :white_check_mark: | :white_check_mark: |
30
+ | **RSS Fallback (zero-setup)** | :white_check_mark: | :x: |
31
31
 
32
32
  ## Quick Start
33
33
 
@@ -39,18 +39,18 @@ Download and open the extension file - Claude Desktop will install it automatica
39
39
 
40
40
  ### Option 2: NPX (No install required)
41
41
 
42
- ```bash
43
- npx reddit-mcp-server
44
- ```
45
-
46
- Or add to your MCP config (Claude Desktop, Cursor, etc.):
42
+ Add to your MCP config (Claude Desktop, Cursor, etc.) with Reddit OAuth credentials:
47
43
 
48
44
  ```json
49
45
  {
50
46
  "mcpServers": {
51
47
  "reddit": {
52
48
  "command": "npx",
53
- "args": ["reddit-mcp-server"]
49
+ "args": ["reddit-mcp-server"],
50
+ "env": {
51
+ "REDDIT_CLIENT_ID": "your_client_id",
52
+ "REDDIT_CLIENT_SECRET": "your_client_secret"
53
+ }
54
54
  }
55
55
  }
56
56
  }
@@ -59,7 +59,8 @@ Or add to your MCP config (Claude Desktop, Cursor, etc.):
59
59
  ### Option 3: Claude Code
60
60
 
61
61
  ```bash
62
- claude mcp add --transport stdio reddit -- npx reddit-mcp-server
62
+ REDDIT_CLIENT_ID=your_client_id REDDIT_CLIENT_SECRET=your_client_secret \
63
+ claude mcp add --transport stdio reddit -- npx reddit-mcp-server
63
64
  ```
64
65
 
65
66
  ## Features
@@ -94,22 +95,22 @@ claude mcp add --transport stdio reddit -- npx reddit-mcp-server
94
95
 
95
96
  ### Environment Variables
96
97
 
97
- | Variable | Required | Default | Description |
98
- | ----------------------- | -------- | -------------- | ------------------------------------------------------------- |
99
- | `REDDIT_CLIENT_ID` | No\* | - | Reddit app client ID |
100
- | `REDDIT_CLIENT_SECRET` | No\* | - | Reddit app client secret |
101
- | `REDDIT_USERNAME` | No | - | Reddit username (for write operations) |
102
- | `REDDIT_PASSWORD` | No | - | Reddit password (for write operations) |
103
- | `REDDIT_USER_AGENT` | No | Auto-generated | Custom User-Agent string |
104
- | `REDDIT_AUTH_MODE` | No | `auto` | Authentication mode: `auto`, `authenticated`, `anonymous` |
105
- | `REDDIT_SAFE_MODE` | No | `standard` | Write safeguards: `off`, `standard`, `strict` |
106
- | `REDDIT_BOT_DISCLOSURE` | No | `off` | Bot disclosure footer: `auto`, `off` |
107
- | `REDDIT_BOT_FOOTER` | No | Built-in | Custom bot footer text (when disclosure is `auto`) |
108
- | `REDDIT_CACHE` | No | `on` | In-memory caching of read requests: `on`, `off` |
109
- | `REDDIT_CACHE_MAX_MB` | No | `50` | Cache size cap in MB (LRU eviction beyond this) |
110
- | `REDDIT_MAX_RETRIES` | No | `3` | Retries on HTTP 429 with Retry-After backoff (`0` to disable) |
111
-
112
- \*Required only if using `authenticated` mode.
98
+ | Variable | Required | Default | Description |
99
+ | ----------------------- | -------- | -------------- | --------------------------------------------------------------------- |
100
+ | `REDDIT_CLIENT_ID` | Yes | - | Reddit app client ID (OAuth required since mid-2026) |
101
+ | `REDDIT_CLIENT_SECRET` | Yes | - | Reddit app client secret |
102
+ | `REDDIT_USERNAME` | No | - | Reddit username (for write operations) |
103
+ | `REDDIT_PASSWORD` | No | - | Reddit password (for write operations) |
104
+ | `REDDIT_USER_AGENT` | No | Auto-generated | Custom User-Agent string |
105
+ | `REDDIT_AUTH_MODE` | No | `auto` | Authentication mode: `auto`, `authenticated` (`anonymous` deprecated) |
106
+ | `REDDIT_SAFE_MODE` | No | `standard` | Write safeguards: `off`, `standard`, `strict` |
107
+ | `REDDIT_BOT_DISCLOSURE` | No | `off` | Bot disclosure footer: `auto`, `off` |
108
+ | `REDDIT_BOT_FOOTER` | No | Built-in | Custom bot footer text (when disclosure is `auto`) |
109
+ | `REDDIT_CACHE` | No | `on` | In-memory caching of read requests: `on`, `off` |
110
+ | `REDDIT_CACHE_MAX_MB` | No | `50` | Cache size cap in MB (LRU eviction beyond this) |
111
+ | `REDDIT_MAX_RETRIES` | No | `3` | Retries on HTTP 429 with Retry-After backoff (`0` to disable) |
112
+
113
+ Reddit closed self-service app creation in November 2025. See [Authentication](#authentication) for how to get credentials.
113
114
 
114
115
  ### Full MCP Config Example
115
116
 
@@ -193,59 +194,64 @@ export REDDIT_BOT_DISCLOSURE=auto
193
194
  export REDDIT_BOT_FOOTER=$'\n\n---\n^(🤖 Custom bot footer text)'
194
195
  ```
195
196
 
196
- ## Authentication Modes
197
+ ## Authentication
198
+
199
+ ### ⚠️ Reddit API Changes (2026)
200
+
201
+ **Anonymous mode no longer works.** As of mid-2026, Reddit blocks all unauthenticated API requests with HTTP 403. OAuth credentials are now required for any API access.
202
+
203
+ Additionally, Reddit closed self-service OAuth app creation in November 2025. New developers must request access through [Reddit's Developer Support](https://support.reddithelp.com/hc/en-us/requests/new?ticket_form_id=14868593862164). Existing OAuth credentials (obtained before November 2025) continue to work.
204
+
205
+ ### Getting Credentials
206
+
207
+ **If you already have a Reddit app** (created at `/prefs/apps` before November 2025): use your existing client ID and secret — they still work at 60-100 req/min.
208
+
209
+ **If you need new credentials**: submit a request through Reddit's Developer Support describing your use case. Approval is required and may take time.
197
210
 
198
211
  ### Mode Comparison
199
212
 
200
- | Mode | Rate Limit | Setup Required | Best For |
201
- | ---------------- | -------------- | -------------- | ------------------------ |
202
- | `anonymous` | ~10 req/min | None | Quick testing, read-only |
203
- | `auto` (default) | 10-100 req/min | Optional | Flexible usage |
204
- | `authenticated` | 60-100 req/min | Required | Production use |
213
+ | Mode | Rate Limit | Setup Required | Tools Available | Best For |
214
+ | ----------------- | -------------- | ----------------- | ---------------------------------------------- | ------------- |
215
+ | `auto` (default) | 60-100 req/min | OAuth credentials | All tools | Most users |
216
+ | `authenticated` | 60-100 req/min | OAuth credentials | All tools | Explicit mode |
217
+ | `auto` (no creds) | ~1 req/min | None | `browse_subreddit`, `get_top_posts` only (RSS) | Quick testing |
218
+ | `anonymous` | ~1 req/min | None | `browse_subreddit`, `get_top_posts` only (RSS) | Legacy alias |
205
219
 
206
- ### Anonymous Mode (Zero Setup)
220
+ ### RSS Fallback Mode
207
221
 
208
- ```json
209
- {
210
- "env": {
211
- "REDDIT_AUTH_MODE": "anonymous"
212
- }
213
- }
214
- ```
222
+ When no OAuth credentials are provided, the server automatically falls back to Reddit's public RSS feeds. This gives you zero-setup access to browse subreddits and get top posts.
215
223
 
216
- **Anonymous mode does not work on every network.** Reddit blocks unauthenticated requests from many IP ranges — datacenters, cloud hosts, VPNs, and addresses it has flagged — and answers with an HTTP 403 block page. If you hit this, tools fail with:
224
+ **What works:** `browse_subreddit` and `get_top_posts` — returns up to 25 posts per request.
217
225
 
218
- ```
219
- Reddit is blocking unauthenticated requests from this network (HTTP 403 with a
220
- block page). Set REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET to authenticate with
221
- OAuth, which also raises the rate limit from ~10 to 60+ requests/min.
222
- ```
226
+ **What's missing compared to OAuth:**
223
227
 
224
- The fix is OAuth credentials — see the next section. This is a property of your network, not of your Reddit account or the subreddit you asked for, so it affects every tool at once. A 403 on a single subreddit while others work is a different thing: that subreddit is private or quarantined.
228
+ - No engagement metrics (score, comments, upvote ratio are all 0)
229
+ - No pagination (single page of ~25 results)
230
+ - No search, user info, comments, or write operations
231
+ - Lower rate limit (~1 req/min vs 60-100 with OAuth)
225
232
 
226
- ### Authenticated Mode (Higher Rate Limits)
233
+ RSS results include a disclaimer noting the data source. All other tools return a clear error directing you to set up OAuth credentials.
227
234
 
228
- 1. Create a Reddit app at https://www.reddit.com/prefs/apps (select "script" type)
229
- 2. Copy the client ID and secret
230
- 3. Configure:
235
+ ### Read-Only Access (OAuth)
231
236
 
232
237
  ```json
233
238
  {
234
239
  "env": {
235
- "REDDIT_AUTH_MODE": "authenticated",
236
240
  "REDDIT_CLIENT_ID": "your_client_id",
237
241
  "REDDIT_CLIENT_SECRET": "your_client_secret"
238
242
  }
239
243
  }
240
244
  ```
241
245
 
242
- ### Write Operations
246
+ ### Write Operations (OAuth + User Credentials)
243
247
 
244
- To create posts, reply, edit, or delete content, you need user credentials:
248
+ To create posts, reply, edit, or delete content, add your Reddit username and password:
245
249
 
246
250
  ```json
247
251
  {
248
252
  "env": {
253
+ "REDDIT_CLIENT_ID": "your_client_id",
254
+ "REDDIT_CLIENT_SECRET": "your_client_secret",
249
255
  "REDDIT_USERNAME": "your_username",
250
256
  "REDDIT_PASSWORD": "your_password",
251
257
  "REDDIT_SAFE_MODE": "standard"
package/dist/bin.js CHANGED
@@ -3,12 +3,12 @@
3
3
  process.env.TRANSPORT_TYPE ??= "stdio";
4
4
  const args = process.argv.slice(2);
5
5
  if (args.includes("--version") || args.includes("-v")) {
6
- console.log("1.5.3");
6
+ console.log("1.6.0");
7
7
  process.exit(0);
8
8
  }
9
9
  if (args.includes("--help") || args.includes("-h")) {
10
10
  console.log(`
11
- Reddit MCP Server v1.5.3
11
+ Reddit MCP Server v1.6.0
12
12
 
13
13
  Usage: reddit-mcp-server [options]
14
14