MCP Reddit Server

A Reddit MCP (Model Context Protocol) server that provides tools for searching subreddits and fetching hot/top posts from the last 24 hours using Reddit's public JSON API.

Features

Tools

1. search_subreddits - Search for subreddits by name or topic

   • Find subreddits matching your search query
   • Returns subreddit name, title, subscriber count, and description

2. get_posts - Get hot or top posts from a subreddit (last 24 hours only)

   • Fetch posts from any subreddit
   • Choose between "hot" or "top" sorting
   • Filter to only posts from the last 24 hours
   • Returns post title, score, body, URL, author, and timestamp
   • Configurable limit (default: 25, max: 100)

Installation

From NPM

npm install -g mcp-reddit-server

From Source

git clone <repository-url>
cd mcp-reddit-server
npm install
npm run build

Usage

With Claude Code (Recommended)

# Add the MCP server to Claude Code
claude mcp add reddit npx -s user mcp-reddit-server

# IMPORTANT: After adding, restart Claude Code for changes to take effect:
# 1. Press Ctrl+C twice to stop Claude Code
# 2. Run: claude --continue to restart

With MCP Inspector (for testing)

npm run inspector

With Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "reddit": {
      "command": "mcp-reddit"
    }
  }
}

Available Tools

1. search_subreddits

Search for subreddits matching a query.

Parameters:

• query (string, required) - Search term to find subreddits

Example:

{
  "name": "search_subreddits",
  "arguments": {
    "query": "programming"
  }
}

Response:

🔍 Found 25 subreddits matching "programming"

1. r/programming - programming
   👥 6,234,567 subscribers
   📝 Computer Programming

2. r/learnprogramming - Learn Programming
   👥 4,567,890 subscribers
   📝 A subreddit for all questions related to programming...

2. get_posts

Get hot or top posts from a subreddit in the last 24 hours.

Parameters:

• subreddit (string, required) - Name of the subreddit (without r/ prefix)
• sort (string, optional) - Sort type: "hot" or "top" (default: "hot")
• limit (number, optional) - Number of posts to retrieve (default: 25, max: 100)

Example:

{
  "name": "get_posts",
  "arguments": {
    "subreddit": "python",
    "sort": "top",
    "limit": 10
  }
}

Response:

🔥 TOP posts from r/python (Last 24 hours)
Found 10 posts
==================================================

Post 1:
📝 **Amazing Python Feature You Didn't Know About**
👤 Author: u/example_user
⬆️ Score: 2543
🔗 URL: https://example.com/article
📄 Post: This is the post content...
🔗 Reddit Link: https://www.reddit.com/r/python/comments/...
🕒 Posted: 10/5/2025, 10:30:00 AM

How It Works

This MCP server uses Reddit's public JSON API, which doesn't require authentication:

• Subreddit Search: https://www.reddit.com/subreddits/search.json?q={query}
• Hot Posts: https://www.reddit.com/r/{subreddit}/hot.json?limit={limit}
• Top Posts (24h): https://www.reddit.com/r/{subreddit}/top.json?limit={limit}&t=day

The server automatically:

• Sets a custom User-Agent to avoid rate limiting
• Filters hot posts to only include posts from the last 24 hours
• Uses Reddit's built-in t=day parameter for top posts
• Formats responses with emojis and clear structure

Development

Build

npm run build

Watch mode

npm run watch

Test with Inspector

npm run inspector

Project Structure

mcp-reddit-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (auto-generated)
├── node_modules/         # Dependencies (auto-generated)
├── package.json          # Project configuration
├── package-lock.json     # Dependency lock (auto-generated)
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

Rate Limiting

Reddit's public API has rate limits. The server sets a custom User-Agent header to help avoid rate limiting issues. If you encounter rate limit errors, wait a few minutes before making more requests.

Limitations

• Posts are limited to the last 24 hours only
• Maximum of 100 posts per request
• Reddit's public API may have rate limits
• Private and banned subreddits are not accessible
• NSFW content filtering depends on Reddit's API defaults

Error Handling

The server provides user-friendly error messages for common issues:

• Invalid subreddit names
• Missing required parameters
• Reddit API errors (404, rate limits, etc.)
• Network connection issues

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

• Built using the Model Context Protocol SDK
• Uses Reddit's public JSON API
• Inspired by the MCP calculator example