Reddit MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants to access to Reddit's API. This server enables Claude/other MCP-compatible AI assistants and Cli to browse subreddits, read posts and comments, post to subreddits, search Reddit, and get user/subreddit information.

Features

Reddit CLI Server

Interact with Reddit from your terminal: browse posts, list flairs, and post to subreddits (with flair support).

Features

• Get top posts from any subreddit

• List available flairs for any subreddit

• Post to any subreddit you have permission for (with or without flair)

• Comprehensive error handling

Installation

Prerequisites

1. Reddit API Credentials

• Go to Reddit App Preferences

• Click "Create another app..."

• Choose "script" as the app type

• Set redirect URI to http://localhost:8080

• Save your Client ID and Client Secret

2. Python Environment

• Python 3.8 or higher

• pip package manager

Setup Steps

1. Clone and install:

2. Configure environment:

3. Environment variables:

With Claude Desktop

Add to your Claude Desktop configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration:

Usage

Start the CLI:

Example Commands

• Get top posts from a subreddit:

  get me top 5 post from python

• List available flairs for a subreddit:

  list flairs for subreddit

• Post to a subreddit with flair:

  post my first post on reddit "This is a test post with flair in my own subreddit. Excited to start TheFoundersLog!" to TheFoundersLog

  Replace <flair_id> with the actual ID from the previous command

• Post to a subreddit without flair:

  post my first post on reddit "This is a test post without flair." to TheFoundersLog

Note:

• Posting requires your Reddit username and password in the .env file.

• Some subreddits restrict posting/flair usage for new accounts or bots.

• For best results, use your own subreddit for testing.

This uses: get_post_details(post_id="url", include_comments=true)

User Profile

Ask Claude: "What can you tell me about Reddit user spez?"

This uses: get_user_profile(username="spez")

Tool Reference

get_subreddit_posts

Browse posts from a specific subreddit.

Parameters:

• subreddit (required): Subreddit name without "r/"

• sort: "hot", "new", "rising", "top" (default: "hot")

• time_filter: For "top" sort - "hour", "day", "week", "month", "year", "all"

• limit: Number of posts (1-100, default: 25)

get_post_details

Get comprehensive information about a specific post.

Parameters:

• post_id (required): Reddit post ID or full URL

• include_comments: Include top comments (default: false)

get_post_comments

Retrieve comments from a post with flexible sorting.

Parameters:

• post_id (required): Reddit post ID or full URL

• sort: "best", "top", "new", "controversial" (default: "best")

• limit: Number of comments (1-100, default: 50)

search_reddit

Search Reddit posts with advanced filtering.

Parameters:

• query (required): Search terms

• subreddit: Limit to specific subreddit (optional)

• sort: "relevance", "hot", "top", "new", "comments" (default: "relevance")

• time_filter: "hour", "day", "week", "month", "year", "all" (default: "all")

• limit: Number of results (1-100, default: 25)

get_user_profile

Get public information about a Reddit user.

Parameters:

• username (required): Reddit username without "u/"

get_subreddit_info

Get detailed information about a subreddit.

Parameters:

• subreddit (required): Subreddit name without "r/"

Error Handling

The server includes comprehensive error handling for:

• Invalid subreddit names

• Non-existent posts or users

• Reddit API rate limits

• Network connectivity issues

• Malformed requests

All errors are returned as descriptive text messages to help users understand what went wrong.

Rate Limiting & Best Practices

• The server respects Reddit's API rate limits (60 requests per minute)

• Implements proper error handling for rate limit exceeded scenarios

• Uses efficient PRAW configurations to minimize API calls

• Includes appropriate User-Agent strings for identification

Security & Privacy

• No authentication storage: Uses app-only authentication (no user tokens)

• Privacy-focused: Only accesses publicly available Reddit data

• No data persistence: Does not store or cache any Reddit data locally

Development

Project Structure

Running Tests

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes

4. Add tests for new functionality

5. Commit your changes (git commit -m 'Add amazing feature')

6. Push to the branch (git push origin feature/amazing-feature)

7. Open a Pull Request

Troubleshooting

Common Issues

"Invalid credentials" error:

• Verify your Reddit API credentials in the .env file

• Ensure the Reddit app is configured as "script" type

• Check that the User-Agent string is properly formatted

"Subreddit not found" error:

• Verify the subreddit name is correct (without "r/" prefix)

• Check if the subreddit is private or banned

• Ensure the subreddit name is spelled correctly

Rate limit errors:

• Wait a few minutes before making more requests

• Consider reducing the limit parameter in your requests

• The server automatically handles most rate limiting scenarios

MCP connection issues:

• Verify the path to server.py in your Claude configuration

• Check that all required environment variables are set

• Ensure Python and dependencies are properly installed

Debug Mode

To run the server with detailed logging:

Changelog

Version 1.0.0

• Initial release

• Core Reddit API tools implementation

• Comprehensive error handling

• Production-ready MCP server

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• MCP Community: MCP Servers Directory

• Reddit API: PRAW Documentation

Related Projects

• Model Context Protocol

• Claude Desktop

• PRAW (Python Reddit API Wrapper)

Built for the MCP community