reddit-mcp-server 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm add:*)",
+      "Bash(pnpm lint)",
+      "Bash(pnpm lint:*)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(npm view:*)",
+      "Bash(npm pack:*)",
+      "Bash(mkdir:*)",
+      "Bash(tar:*)",
+      "Bash(ls:*)",
+      "Bash(rm:*)"
+    ],
+    "deny": []
+  }
+}

package/.env.example

@@ -0,0 +1,7 @@
+# Reddit API Credentials (required)
+REDDIT_CLIENT_ID=
+REDDIT_CLIENT_SECRET=
+
+# Reddit User Credentials (optional, for posting/commenting)
+REDDIT_USERNAME=
+REDDIT_PASSWORD=

package/.prettierignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+build
+.pnpm-store
+pnpm-lock.yaml
+*.log
+.env

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "printWidth": 120,
+  "tabWidth": 2,
+  "endOfLine": "auto"
+}

package/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Reddit MCP (Model Context Protocol) server that provides tools for interacting with the Reddit API. It's built with TypeScript and uses the MCP SDK to expose Reddit functionality as tools that can be used by AI assistants.
+
+## Development Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build TypeScript to JavaScript with tsup
+pnpm build
+
+# Run the MCP inspector for development/testing
+pnpm inspect
+
+# Build and run inspector in one command
+pnpm dev
+
+# Build and start the server via npx
+pnpm start
+
+# Format code with Prettier
+pnpm format
+
+# Check code formatting
+pnpm format:check
+
+# Lint code with ESLint
+pnpm lint
+
+# Fix linting issues
+pnpm lint:fix
+```
+
+## Architecture
+
+### Core Components
+
+1. **Reddit Client** (`src/client/reddit-client.ts`): Singleton pattern implementation that handles:
+   - OAuth2 authentication (client credentials and password flow)
+   - Automatic token refresh via axios interceptors
+   - Rate limiting and error handling
+   - Both read-only and authenticated operations
+
+2. **Tool Modules** (`src/tools/`): Modular organization by functionality:
+   - `post-tools.ts`: Post creation, replying to posts/comments
+   - `subreddit-tools.ts`: Subreddit info, statistics, trending
+   - `user-tools.ts`: User information and engagement insights
+
+3. **Type Definitions** (`src/types.ts`): Comprehensive TypeScript types for all Reddit entities
+
+### Authentication Flow
+
+- **Read-only operations**: Only require client credentials (REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET)
+- **Write operations**: Additionally require user credentials (REDDIT_USERNAME, REDDIT_PASSWORD)
+- Token management is handled automatically by the Reddit client
+
+## Environment Setup
+
+Required environment variables:
+```bash
+REDDIT_CLIENT_ID=your_client_id
+REDDIT_CLIENT_SECRET=your_client_secret
+REDDIT_USER_AGENT=YourApp/1.0.0  # Optional, defaults to "RedditMCPServer/0.1.0"
+REDDIT_USERNAME=your_username     # Optional, for write operations
+REDDIT_PASSWORD=your_password     # Optional, for write operations
+```
+
+## Key Implementation Details
+
+1. **Error Handling**: All tools use try-catch blocks and return MCP-compliant error responses
+2. **Rate Limiting**: Built into the Reddit client to respect API limits
+3. **Token Refresh**: Automatic via axios interceptors when tokens expire
+4. **Singleton Client**: Ensures single authenticated instance across all tools
+
+## Testing Approach
+
+Currently no test framework is configured. When implementing tests:
+- Use the MCP inspector (`pnpm inspect`) for manual testing
+- Test both authenticated and unauthenticated flows
+- Verify error handling for invalid inputs and API failures
+
+## Common Development Tasks
+
+1. **Adding a new Reddit tool**:
+   - Create new function in appropriate tool file (`src/tools/`)
+   - Define TypeScript types in `src/types.ts` if needed
+   - Export from `src/tools/index.ts`
+   - Register in main server (`src/index.ts`)
+
+2. **Modifying Reddit client**:
+   - Update `src/client/reddit-client.ts`
+   - Ensure backward compatibility with existing tools
+   - Test both auth flows if authentication logic changes
+
+3. **Debugging**:
+   - Use `pnpm inspect` to test tools interactively
+   - Check axios interceptors for auth issues
+   - Verify environment variables are set correctly

package/Dockerfile

@@ -0,0 +1,17 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
+FROM node:lts-alpine
+
+WORKDIR /app
+
+# Install dependencies without running prepare scripts
+COPY package*.json ./
+RUN npm install --ignore-scripts && npm install dotenv @types/dotenv
+
+# Copy all source files
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Default command to start the MCP server via stdio transport
+CMD ["node", "build/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandros Lekkas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Reddit MCP Server ⚙️
+
+A Model Context Protocol (MCP) that provides tools for fetching and creating Reddit 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.
+
+[![smithery badge](https://smithery.ai/badge/@jordanburke/reddit-mcp-server)](https://smithery.ai/server/@jordanburke/reddit-mcp-server)
+
+https://github.com/user-attachments/assets/caa37704-7c92-4bf8-b7e8-56d02ccb4983
+
+## 🧑‍💻 About
+
+https://www.linkedin.com/feed/update/urn:li:activity:7328864060534419457/
+
+![image](https://github.com/user-attachments/assets/aedc0966-75d4-45c4-a384-df03d232e29d)
+
+## 🔧 Available Tools (Features)
+
+**Read-only Tools (Client Credentials):**
+
+- `get_user_info(username)` - Get detailed user analysis with engagement insights
+- `get_top_posts(subreddit, time_filter, limit)` - Get and analyze top posts
+- `get_subreddit_stats(subreddit)` - Get comprehensive subreddit analysis
+- `get_trending_subreddits()` - Get list of trending subreddits
+
+**Read-write Tools (User Credentials):**
+
+- `create_post(subreddit, title, content, flair, is_self)` - Create an optimized post
+- `reply_to_post(post_id, content, subreddit)` - Add a reply with engagement insights
+- `reply_to_comment(comment_id, content, subreddit)` - Add a strategic reply
+
+## 🔌 Installation
+
+### Installing via Smithery
+
+To install Reddit Content Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@alexandros-lekkas/reddit-mcp-server):
+
+```bash
+npx -y @smithery/cli install @jordanburke/reddit-mcp-server --client claude
+```
+
+### 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` (don't worry, I won't steal them 😜)
+
+5. Install dependencies with `pnpm install`
+
+6. 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)
+
+7. If the connection works, add this to your MCP config (for Cursor or Claude, depending on which agent you are using)
+
+```json
+  "mcpServers": {
+    "reddit": {
+      "command": "npx",
+      "args": [
+        "reddit-mcp-server"
+      ],
+      "env": {
+        "REDDIT_CLIENT_ID": "😜",
+        "REDDIT_CLIENT_SECRET": "😜",
+        "REDDIT_USERNAME": "😜",
+        "REDDIT_PASSWORD": "😜"
+      },
+      "autoApprove": [
+        "get_reddit_post",
+        "get_top_posts",
+        "get_user_info",
+        "get_subreddit_info",
+        "get_trending_subreddits",
+        "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
+    }
+  }
+```
+
+(Make sure to replace the environmental variables with your actual keys, not the 😜 emoji)
+
+## 📚 Credits
+
+- This is a fork of the original [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas.
+
+- Credit goes to the [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200 for the inspiration and implementation of these tools. This repository is, at the moment, simply a Node.js port of the Python implementation.
+
+- Credit goes to [Eugene Sh](https://medium.com/@eugenesh4work/how-to-build-an-mcp-server-fast-a-step-by-step-tutorial-e09faa5f7e3b) for the tutorial on how to build an MCP server (which was used as a reference for this implementation).

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node