npm - reddit-mcp-server - Versions diffs - 1.1.1 → 1.2.0 - Mend

reddit-mcp-server 1.1.1 → 1.2.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 (9) hide show

package/README.md CHANGED Viewed

@@ -1,460 +1,289 @@
-# Reddit MCP Server ⚙️
+# Reddit MCP Server
-A Model Context Protocol (MCP) that provides tools for fetching and creating Reddit content.
+A Model Context Protocol (MCP) server for interacting with Reddit - fetch posts, comments, user info, and **create content**.
-> **Note**: This is a fork of the original [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas, updated with pnpm, tsup build system, and npx execution support.
+[![npm version](https://img.shields.io/npm/v/reddit-mcp-server.svg)](https://www.npmjs.com/package/reddit-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/reddit-mcp-server.svg)](https://www.npmjs.com/package/reddit-mcp-server)
+[![GitHub stars](https://img.shields.io/github/stars/jordanburke/reddit-mcp-server.svg?style=flat&logo=github)](https://github.com/jordanburke/reddit-mcp-server/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-## 🔧 Available Tools (Features)
+<a href="https://glama.ai/mcp/servers/@jordanburke/reddit-mcp-server">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@jordanburke/reddit-mcp-server/badge" alt="reddit-mcp-server MCP server" />
+</a>
-**Read-only Tools (Client Credentials):**
+## Features at a Glance
-- `get_reddit_post(subreddit, post_id)` - Get a specific Reddit post
-- `get_top_posts(subreddit, time_filter, limit)` - Get top posts from a subreddit
-- `get_user_info(username)` - Get information about a Reddit user
-- `get_subreddit_info(subreddit_name)` - Get information about a subreddit
-- `get_trending_subreddits()` - Get currently trending subreddits
-- `search_reddit(query, subreddit?, sort?, time_filter?, limit?, type?)` - Search for posts on Reddit
-- `get_post_comments(post_id, subreddit, sort?, limit?)` - Get comments for a specific Reddit post
-- `get_user_posts(username, sort?, time_filter?, limit?)` - Get posts submitted by a specific user
-- `get_user_comments(username, sort?, time_filter?, limit?)` - Get comments made by a specific user
+| Feature                         | reddit-mcp-server  | Other Reddit MCPs  |
+| ------------------------------- | :----------------: | :----------------: |
+| **Create Posts**                | :white_check_mark: |        :x:         |
+| **Reply to Posts/Comments**     | :white_check_mark: |        :x:         |
+| **Edit Posts/Comments**         | :white_check_mark: |        :x:         |
+| **Delete Posts/Comments**       | :white_check_mark: |        :x:         |
+| **Spam Protection (Safe Mode)** | :white_check_mark: |        :x:         |
+| Browse Subreddits               | :white_check_mark: | :white_check_mark: |
+| Search Reddit                   | :white_check_mark: | :white_check_mark: |
+| User Analysis                   | :white_check_mark: | :white_check_mark: |
+| Post Comments                   | :white_check_mark: | :white_check_mark: |
+| Zero-Setup Anonymous Mode       | :white_check_mark: | :white_check_mark: |
+| Three-Tier Auth (10/60/100 rpm) | :white_check_mark: | :white_check_mark: |
-**Write Tools (User Credentials Required):**
+## Quick Start
-- `create_post(subreddit, title, content, is_self)` - Create a new post in a subreddit
-- `reply_to_post(post_id, content, subreddit?)` - Post a reply to an existing Reddit post
+### Option 1: Claude Desktop Extension (Easiest)
-## 🔌 Installation
+Download and open the extension file - Claude Desktop will install it automatically:
-### Installing via Smithery
+**[Download reddit-mcp-server.mcpb](https://github.com/jordanburke/reddit-mcp-server/releases/latest/download/reddit-mcp-server.mcpb)**
-To install Reddit Content Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@jordanburke/reddit-mcp-server):
+### Option 2: NPX (No install required)
 ```bash
-npx -y @smithery/cli install reddit-mcp-server --client claude
+npx reddit-mcp-server
 ```
-### Manual Installation
-1. `git clone https://github.com/jordanburke/reddit-mcp-server`
-2. Create a Reddit app [here](https://www.reddit.com/prefs/apps)
-![image](https://github.com/user-attachments/assets/bb7582d6-abf2-4282-a102-bd2e0f2c1c41)
-Make sure to select "script"!
-3. Copy the client ID and client secret
-4. Create a `.env` file based on `.env.example`
-Do this with your `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET`
-If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDIT_PASSWORD`
-5. Install dependencies with `pnpm install`
-6. Build the project with `pnpm build`
-7. Run with `pnpm dev` and open the inspection server (http://127.0.0.1:6274/)
-![image](https://github.com/user-attachments/assets/705c63ef-5d3c-4a68-8d3b-18dfda0a29f2)
-8. If the connection works, add this to your MCP config (for Cursor or Claude Desktop)
+Or add to your MCP config (Claude Desktop, Cursor, etc.):
 ```json
+{
   "mcpServers": {
     "reddit": {
       "command": "npx",
-      "args": [
-        "reddit-mcp-server"
-      ],
-      "env": {
-        "REDDIT_CLIENT_ID": "<YOUR_CLIENT_ID>",
-        "REDDIT_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
-        "REDDIT_USERNAME": "<YOUR_USERNAME_OPTIONAL>",
-        "REDDIT_PASSWORD": "<YOUR_PASSWORD_OPTIONAL>"
-      },
-      "autoApprove": [
-        "get_reddit_post",
-        "get_top_posts",
-        "get_user_info",
-        "get_subreddit_info",
-        "get_trending_subreddits",
-        "search_reddit",
-        "get_post_comments",
-        "get_user_posts",
-        "get_user_comments",
-        "create_post",
-        "reply_to_post"
-      ] // You don't need to add this, but it makes it so that you don't have to keep clicking approve
+      "args": ["reddit-mcp-server"]
     }
   }
+}
 ```
-## 🛠️ Development
-### Commands
+### Option 3: Claude Code
 ```bash
-# Install dependencies
-pnpm install
-# Build TypeScript to JavaScript
-pnpm build
+claude mcp add --transport stdio reddit -- npx reddit-mcp-server
+```
-# Run the MCP inspector for development/testing
-pnpm inspect
+## Features
-# Build and run inspector in one command
-pnpm dev
+### Read-only Tools
-# Run tests
-pnpm test
+| Tool                      | Description                                         |
+| ------------------------- | --------------------------------------------------- |
+| `get_reddit_post`         | Get a specific Reddit post with engagement analysis |
+| `get_top_posts`           | Get top posts from a subreddit or home feed         |
+| `get_user_info`           | Get detailed information about a Reddit user        |
+| `get_user_posts`          | Get posts submitted by a specific user              |
+| `get_user_comments`       | Get comments made by a specific user                |
+| `get_subreddit_info`      | Get subreddit details and statistics                |
+| `get_trending_subreddits` | Get currently trending subreddits                   |
+| `get_post_comments`       | Get comments from a specific post with threading    |
+| `search_reddit`           | Search for posts across Reddit                      |
-# Lint code
-pnpm lint
+### Write Tools (Require User Credentials)
-# Format code
-pnpm format
-```
+| Tool             | Description                                 |
+| ---------------- | ------------------------------------------- |
+| `create_post`    | Create a new post in a subreddit            |
+| `reply_to_post`  | Post a reply to an existing post or comment |
+| `edit_post`      | Edit your own Reddit post (self-text only)  |
+| `edit_comment`   | Edit your own Reddit comment                |
+| `delete_post`    | Permanently delete your own post            |
+| `delete_comment` | Permanently delete your own comment         |
-### Version & Help
+## Configuration
-```bash
-# Check version
-npx reddit-mcp-server --version
+### Environment Variables
-# Show help
-npx reddit-mcp-server --help
+| Variable               | Required | Default        | Description                                               |
+| ---------------------- | -------- | -------------- | --------------------------------------------------------- |
+| `REDDIT_CLIENT_ID`     | No\*     | -              | Reddit app client ID                                      |
+| `REDDIT_CLIENT_SECRET` | No\*     | -              | Reddit app client secret                                  |
+| `REDDIT_USERNAME`      | No       | -              | Reddit username (for write operations)                    |
+| `REDDIT_PASSWORD`      | No       | -              | Reddit password (for write operations)                    |
+| `REDDIT_USER_AGENT`    | No       | Auto-generated | Custom User-Agent string                                  |
+| `REDDIT_AUTH_MODE`     | No       | `auto`         | Authentication mode: `auto`, `authenticated`, `anonymous` |
+| `REDDIT_SAFE_MODE`     | No       | `off`          | Write safeguards: `off`, `standard`, `strict`             |
-# Generate OAuth token for HTTP server
-npx reddit-mcp-server --generate-token
-```
+\*Required only if using `authenticated` mode.
-### Streamable MCP Endpoint (Hono Server)
+### Full MCP Config Example
-In addition to the standard npx execution, this server also supports a Streamable MCP endpoint via Hono for direct HTTP integration:
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "npx",
+      "args": ["reddit-mcp-server"],
+      "env": {
+        "REDDIT_CLIENT_ID": "your_client_id",
+        "REDDIT_CLIENT_SECRET": "your_client_secret",
+        "REDDIT_USERNAME": "your_username",
+        "REDDIT_PASSWORD": "your_password",
+        "REDDIT_SAFE_MODE": "standard"
+      }
+    }
+  }
+}
+```
-```bash
-# Start the Hono server on port 3000 (default)
-pnpm serve
+## Safe Mode (Spam Protection)
-# Start with custom port
-PORT=8080 pnpm serve
+**New!** Protect your Reddit account from spam detection and bans with built-in safeguards.
-# Development mode with auto-reload
-pnpm serve:dev
-```
+### Why Use Safe Mode?
-The server will be available at `http://localhost:3000` with the MCP endpoint at `http://localhost:3000/mcp`.
+Reddit's spam detection can flag accounts for:
-#### OAuth Security (Optional)
+- Rapid posting or commenting
+- Duplicate or similar content
+- Non-standard User-Agent strings
-The HTTP server supports optional OAuth protection to secure your endpoints:
+Safe Mode helps prevent these issues automatically.
-**Generate a secure token:**
+### Mode Options
-```bash
-npx reddit-mcp-server --generate-token
-# Output: Generated OAuth token: A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j
-```
+| Mode       | Write Delay | Duplicate Detection | Use Case                       |
+| ---------- | ----------- | ------------------- | ------------------------------ |
+| `off`      | None        | No                  | Default, no safeguards         |
+| `standard` | 2 seconds   | Last 10 items       | Recommended for normal use     |
+| `strict`   | 5 seconds   | Last 20 items       | For cautious automated posting |
-**Enable OAuth with generated token:**
+### Enable Safe Mode
 ```bash
-export OAUTH_ENABLED=true
-export OAUTH_TOKEN="A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j"
-pnpm serve
+export REDDIT_SAFE_MODE=standard
+npx reddit-mcp-server
 ```
-**Make authenticated requests:**
+Or in your MCP config:
-```bash
-curl -H "Authorization: Bearer A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j" \
-     -H "Content-Type: application/json" \
-     -d '{"method":"tools/list","params":{}}' \
-     http://localhost:3000/mcp
+```json
+{
+  "env": {
+    "REDDIT_SAFE_MODE": "standard"
+  }
+}
 ```
-**OAuth Configuration:**
+### What Safe Mode Does
-- `OAUTH_ENABLED=true` - Enables OAuth protection (disabled by default)
-- `OAUTH_TOKEN=your-token` - Your custom token (or use `--generate-token`)
-- Without OAuth, the server is accessible without authentication
-- Health check (`/`) is always unprotected; only `/mcp` requires authentication
+1. **Rate Limiting**: Enforces minimum delays between write operations
+2. **Duplicate Detection**: Blocks identical content from being posted twice
+3. **Smart User-Agent**: Auto-generates Reddit-compliant User-Agent format when username is provided
-#### MCP Client Configuration
+## Authentication Modes
-For MCP clients connecting to an OAuth-protected server, configure according to the [MCP Authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization):
+### Mode Comparison
-**HTTP-based MCP Clients (e.g., web applications):**
-```javascript
-// Example using fetch API
-const response = await fetch("http://localhost:3000/mcp", {
-  method: "POST",
-  headers: {
-    Authorization: "Bearer YOUR_TOKEN",
-    "Content-Type": "application/json",
-  },
-  body: JSON.stringify({
-    jsonrpc: "2.0",
-    id: 1,
-    method: "tools/list",
-    params: {},
-  }),
-})
-const result = await response.json()
-```
+| Mode             | Rate Limit     | Setup Required | Best For                 |
+| ---------------- | -------------- | -------------- | ------------------------ |
+| `anonymous`      | ~10 req/min    | None           | Quick testing, read-only |
+| `auto` (default) | 10-100 req/min | Optional       | Flexible usage           |
+| `authenticated`  | 60-100 req/min | Required       | Production use           |
-**Direct HTTP MCP Client:**
-```javascript
-const client = new MCP.Client({
-  transport: new MCP.HTTPTransport({
-    url: "http://localhost:3000/mcp",
-    headers: {
-      Authorization: "Bearer YOUR_TOKEN",
-    },
-  }),
-})
-```
+### Anonymous Mode (Zero Setup)
-**Custom MCP Client Implementation:**
-```typescript
-import { Client } from "@modelcontextprotocol/sdk/client/index.js"
-import { HTTPTransport } from "@modelcontextprotocol/sdk/client/http.js"
-const transport = new HTTPTransport({
-  url: "http://localhost:3000/mcp",
-  headers: {
-    Authorization: "Bearer YOUR_TOKEN",
-    "Content-Type": "application/json",
-  },
-})
-const client = new Client(
-  {
-    name: "reddit-client",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {},
-  },
-)
-await client.connect(transport)
+```json
+{
+  "env": {
+    "REDDIT_AUTH_MODE": "anonymous"
+  }
+}
 ```
-**Important Notes:**
-- Replace `YOUR_TOKEN` with your generated OAuth token
-- Authorization header MUST be included in every request to `/mcp`
-- Tokens MUST NOT be included in URI query strings per MCP specification
-- Use HTTPS in production for secure token transmission
-**For Remote/Deployed Servers:**
-When connecting to a remote Reddit MCP server (e.g., deployed on your infrastructure):
-```javascript
-// Production server with OAuth
-const response = await fetch("https://your-server.com/mcp", {
-  method: "POST",
-  headers: {
-    Authorization: "Bearer YOUR_TOKEN",
-    "Content-Type": "application/json",
-  },
-  body: JSON.stringify({
-    jsonrpc: "2.0",
-    id: 1,
-    method: "tools/list",
-    params: {},
-  }),
-})
-```
+### Authenticated Mode (Higher Rate Limits)
-**MCP Client Configuration for Remote Server:**
-```typescript
-import { Client } from "@modelcontextprotocol/sdk/client/index.js"
-import { HTTPTransport } from "@modelcontextprotocol/sdk/client/http.js"
-// For your deployed server
-const transport = new HTTPTransport({
-  url: "https://your-reddit-mcp.company.com/mcp",
-  headers: {
-    Authorization: "Bearer YOUR_GENERATED_TOKEN",
-    "Content-Type": "application/json",
-  },
-})
-const client = new Client(
-  {
-    name: "reddit-client",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {},
-  },
-)
-await client.connect(transport)
-```
-**Claude Desktop/Cursor with Remote Server (HTTP):**
-For remote servers, you can use a proxy approach:
+1. Create a Reddit app at https://www.reddit.com/prefs/apps (select "script" type)
+2. Copy the client ID and secret
+3. Configure:
 ```json
 {
-  "mcpServers": {
-    "reddit-remote": {
-      "command": "node",
-      "args": [
-        "-e",
-        "const http = require('https'); const req = http.request('https://your-server.com/mcp', {method:'POST',headers:{'Authorization':'Bearer YOUR_TOKEN','Content-Type':'application/json'}}, res => res.pipe(process.stdout)); process.stdin.pipe(req);"
-      ],
-      "env": {}
-    }
+  "env": {
+    "REDDIT_AUTH_MODE": "authenticated",
+    "REDDIT_CLIENT_ID": "your_client_id",
+    "REDDIT_CLIENT_SECRET": "your_client_secret"
   }
 }
 ```
-**For Claude Desktop/Cursor (stdio transport):**
-OAuth is not applicable when using the traditional npx execution method. Use the stdio configuration instead:
+### Write Operations
+To create posts, reply, edit, or delete content, you need user credentials:
 ```json
 {
-  "mcpServers": {
-    "reddit": {
-      "command": "npx",
-      "args": ["reddit-mcp-server"],
-      "env": {
-        "REDDIT_CLIENT_ID": "your_client_id",
-        "REDDIT_CLIENT_SECRET": "your_client_secret"
-      }
-    }
+  "env": {
+    "REDDIT_USERNAME": "your_username",
+    "REDDIT_PASSWORD": "your_password",
+    "REDDIT_SAFE_MODE": "standard"
   }
 }
 ```
-#### Remote Deployment Examples
+## Development
-**Deploy to your infrastructure and share the URL:**
-1. **Generate secure token:**
+### Commands
-   ```bash
-   npx reddit-mcp-server --generate-token
-   # Output: Generated OAuth token: xyz123abc456def789
-   ```
+```bash
+pnpm install        # Install dependencies
+pnpm build          # Build TypeScript
+pnpm dev            # Build and run MCP inspector
+pnpm test           # Run tests
+pnpm lint           # Lint code
+pnpm format         # Format code
+```
-2. **Deploy with Docker on your server:**
+### CLI Options
-   ```bash
-   docker run -d \
-     --name reddit-mcp \
-     -p 3000:3000 \
-     -e REDDIT_CLIENT_ID=your_reddit_client_id \
-     -e REDDIT_CLIENT_SECRET=your_reddit_client_secret \
-     -e OAUTH_ENABLED=true \
-     -e OAUTH_TOKEN=xyz123abc456def789 \
-     ghcr.io/jordanburke/reddit-mcp-server:latest
-   ```
+```bash
+npx reddit-mcp-server --version         # Show version
+npx reddit-mcp-server --help            # Show help
+npx reddit-mcp-server --generate-token  # Generate OAuth token for HTTP mode
+```
-3. **Share with your team:**
+## HTTP Server Mode
-   ```
-   Server URL: https://your-server.com/mcp
-   OAuth Token: xyz123abc456def789
-   ```
+For Docker deployments or web-based clients, use HTTP transport:
-4. **Team members connect:**
-   ```typescript
-   const client = new Client(...);
-   const transport = new HTTPTransport({
-     url: 'https://your-server.com/mcp',
-     headers: { 'Authorization': 'Bearer xyz123abc456def789' }
-   });
-   await client.connect(transport);
-   ```
+```bash
+TRANSPORT_TYPE=httpStream PORT=3000 node dist/index.js
+```
-This allows integration with systems that support HTTP-based MCP communication, similar to the cq-api and agent-todo implementations.
+### With OAuth Protection
-## 🐳 Docker Usage
+```bash
+export OAUTH_ENABLED=true
+export OAUTH_TOKEN=$(npx reddit-mcp-server --generate-token | tail -1)
+TRANSPORT_TYPE=httpStream node dist/index.js
+```
-### Pull from GitHub Container Registry
+Make authenticated requests:
 ```bash
-# Pull the latest image
-docker pull ghcr.io/jordanburke/reddit-mcp-server:latest
-# Pull a specific version
-docker pull ghcr.io/jordanburke/reddit-mcp-server:v1.0.10
+curl -H "Authorization: Bearer $OAUTH_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"method":"tools/list","params":{}}' \
+     http://localhost:3000/mcp
 ```
-### Run with Docker
+## Docker
+### Quick Start
 ```bash
-# Run the HTTP server (recommended)
-docker run -d \
-  --name reddit-mcp \
-  -p 3000:3000 \
-  -e REDDIT_CLIENT_ID=your_client_id \
-  -e REDDIT_CLIENT_SECRET=your_client_secret \
-  -e REDDIT_USERNAME=your_username \
-  -e REDDIT_PASSWORD=your_password \
-  ghcr.io/jordanburke/reddit-mcp-server:latest
+# Pull and run
+docker pull ghcr.io/jordanburke/reddit-mcp-server:latest
-# Run with OAuth enabled (secure)
 docker run -d \
   --name reddit-mcp \
   -p 3000:3000 \
   -e REDDIT_CLIENT_ID=your_client_id \
   -e REDDIT_CLIENT_SECRET=your_client_secret \
-  -e OAUTH_ENABLED=true \
-  -e OAUTH_TOKEN=your_generated_token \
+  -e REDDIT_SAFE_MODE=standard \
   ghcr.io/jordanburke/reddit-mcp-server:latest
-# Run with custom port
-docker run -d \
-  --name reddit-mcp \
-  -p 8080:3000 \
-  --env-file .env \
-  ghcr.io/jordanburke/reddit-mcp-server:latest
-# Generate token using Docker
-docker run --rm \
-  ghcr.io/jordanburke/reddit-mcp-server:latest \
-  node dist/bin.js --generate-token
-# Run as stdio MCP server (for direct integration)
-docker run -it \
-  --env-file .env \
-  ghcr.io/jordanburke/reddit-mcp-server:latest \
-  node dist/index.js
 ```
-### Build Locally
-```bash
-# Build the image
-docker build -t reddit-mcp-server .
-# Run the locally built image
-docker run -d \
-  --name reddit-mcp \
-  -p 3000:3000 \
-  --env-file .env \
-  reddit-mcp-server
-```
-### Docker Compose Example
+### Docker Compose
 ```yaml
-version: "3.8"
 services:
   reddit-mcp:
     image: ghcr.io/jordanburke/reddit-mcp-server:latest
@@ -465,14 +294,20 @@ services:
       - REDDIT_CLIENT_SECRET=${REDDIT_CLIENT_SECRET}
       - REDDIT_USERNAME=${REDDIT_USERNAME}
       - REDDIT_PASSWORD=${REDDIT_PASSWORD}
-      # Optional OAuth settings
+      - REDDIT_SAFE_MODE=standard
       - OAUTH_ENABLED=${OAUTH_ENABLED:-false}
       - OAUTH_TOKEN=${OAUTH_TOKEN}
     restart: unless-stopped
 ```
-## 📚 Credits
+### Build Locally
+```bash
+docker build -t reddit-mcp-server .
+docker run -d --name reddit-mcp -p 3000:3000 --env-file .env reddit-mcp-server
+```
-- This is a fork of the original [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas.
+## Credits
-- Credit goes to the [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200 for the inspiration and implementation of these tools.
+- Fork of [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas
+- Inspired by [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200

package/dist/bin.d.ts CHANGED Viewed

	@@ -1 +1 @@
1	- ~~#!/usr/bin/env~~ ~~node~~
1	+ export { };