reddit-mcp-server 1.5.2 → 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 +62 -46
  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,49 +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.
223
+
224
+ **What works:** `browse_subreddit` and `get_top_posts` — returns up to 25 posts per request.
215
225
 
216
- ### Authenticated Mode (Higher Rate Limits)
226
+ **What's missing compared to OAuth:**
217
227
 
218
- 1. Create a Reddit app at https://www.reddit.com/prefs/apps (select "script" type)
219
- 2. Copy the client ID and secret
220
- 3. Configure:
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)
232
+
233
+ RSS results include a disclaimer noting the data source. All other tools return a clear error directing you to set up OAuth credentials.
234
+
235
+ ### Read-Only Access (OAuth)
221
236
 
222
237
  ```json
223
238
  {
224
239
  "env": {
225
- "REDDIT_AUTH_MODE": "authenticated",
226
240
  "REDDIT_CLIENT_ID": "your_client_id",
227
241
  "REDDIT_CLIENT_SECRET": "your_client_secret"
228
242
  }
229
243
  }
230
244
  ```
231
245
 
232
- ### Write Operations
246
+ ### Write Operations (OAuth + User Credentials)
233
247
 
234
- 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:
235
249
 
236
250
  ```json
237
251
  {
238
252
  "env": {
253
+ "REDDIT_CLIENT_ID": "your_client_id",
254
+ "REDDIT_CLIENT_SECRET": "your_client_secret",
239
255
  "REDDIT_USERNAME": "your_username",
240
256
  "REDDIT_PASSWORD": "your_password",
241
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.2");
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.2
11
+ Reddit MCP Server v1.6.0
12
12
 
13
13
  Usage: reddit-mcp-server [options]
14
14