JUHE API Marketplace
jordanburke avatar
MCP Server

reddit-mcp-server

A Model Context Protocol (MCP) that provides tools for fetching and creating Reddit content.

3
GitHub Stars
8/22/2025
Last Updated
No Configuration
Please check the documentation below.

README Documentation

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 by Alexandros Lekkas, updated with pnpm, tsup build system, and npx execution support.

🔧 Available Tools (Features)

Read-only Tools (Client Credentials):

  • 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

Write Tools (User Credentials Required):

  • 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

🔌 Installation

Installing via Smithery

To install Reddit Content Integration Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install reddit-mcp-server --client claude

Manual Installation

  1. git clone https://github.com/jordanburke/reddit-mcp-server

  2. Create a Reddit app here

image

Make sure to select "script"!

  1. Copy the client ID and client secret

  2. 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

  1. Install dependencies with pnpm install

  2. Build the project with pnpm build

  3. Run with pnpm dev and open the inspection server (http://127.0.0.1:6274/)

image

  1. If the connection works, add this to your MCP config (for Cursor or Claude Desktop)
  "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
    }
  }

🛠️ Development

Commands

# Install dependencies
pnpm install

# Build TypeScript to JavaScript
pnpm build

# Run the MCP inspector for development/testing
pnpm inspect

# Build and run inspector in one command
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

Version & Help

# Check version
npx reddit-mcp-server --version

# Show help
npx reddit-mcp-server --help

# Generate OAuth token for HTTP server
npx reddit-mcp-server --generate-token

Streamable MCP Endpoint (Hono Server)

In addition to the standard npx execution, this server also supports a Streamable MCP endpoint via Hono for direct HTTP integration:

# Start the Hono server on port 3000 (default)
pnpm serve

# Start with custom port
PORT=8080 pnpm serve

# Development mode with auto-reload
pnpm serve:dev

The server will be available at http://localhost:3000 with the MCP endpoint at http://localhost:3000/mcp.

OAuth Security (Optional)

The HTTP server supports optional OAuth protection to secure your endpoints:

Generate a secure token:

npx reddit-mcp-server --generate-token
# Output: Generated OAuth token: A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j

Enable OAuth with generated token:

export OAUTH_ENABLED=true
export OAUTH_TOKEN="A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j"
pnpm serve

Make authenticated requests:

curl -H "Authorization: Bearer A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j" \
     -H "Content-Type: application/json" \
     -d '{"method":"tools/list","params":{}}' \
     http://localhost:3000/mcp

OAuth Configuration:

  • 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

MCP Client Configuration

For MCP clients connecting to an OAuth-protected server, configure according to the MCP Authorization specification:

HTTP-based MCP Clients (e.g., web applications):

// 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();

Direct HTTP MCP Client:

const client = new MCP.Client({
  transport: new MCP.HTTPTransport({
    url: 'http://localhost:3000/mcp',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  })
});

Custom MCP Client Implementation:

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);

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):

// 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: {}
  })
});

MCP Client Configuration for Remote Server:

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:

{
  "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": {}
    }
  }
}

For Claude Desktop/Cursor (stdio transport): OAuth is not applicable when using the traditional npx execution method. Use the stdio configuration instead:

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["reddit-mcp-server"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Remote Deployment Examples

Deploy to your infrastructure and share the URL:

  1. Generate secure token:

    npx reddit-mcp-server --generate-token
# Output: Generated OAuth token: xyz123abc456def789

  2. Deploy with Docker on your server:

    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

  3. Share with your team:

    Server URL: https://your-server.com/mcp
OAuth Token: xyz123abc456def789

  4. Team members connect:

    const client = new Client(...);
const transport = new HTTPTransport({
  url: 'https://your-server.com/mcp',
  headers: { 'Authorization': 'Bearer xyz123abc456def789' }
});
await client.connect(transport);

This allows integration with systems that support HTTP-based MCP communication, similar to the cq-api and agent-todo implementations.

🐳 Docker Usage

Pull from GitHub Container Registry

# 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

Run with Docker

# 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

# 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 \
  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

# 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

version: '3.8'

services:
  reddit-mcp:
    image: ghcr.io/jordanburke/reddit-mcp-server:latest
    ports:
      - "3000:3000"
    environment:
      - REDDIT_CLIENT_ID=${REDDIT_CLIENT_ID}
      - REDDIT_CLIENT_SECRET=${REDDIT_CLIENT_SECRET}
      - REDDIT_USERNAME=${REDDIT_USERNAME}
      - REDDIT_PASSWORD=${REDDIT_PASSWORD}
      # Optional OAuth settings
      - OAUTH_ENABLED=${OAUTH_ENABLED:-false}
      - OAUTH_TOKEN=${OAUTH_TOKEN}
    restart: unless-stopped

📚 Credits

Quick Actions

View on GitHubView All Servers

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source