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

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

Python Environment

Python 3.8 or higher
pip package manager

Setup Steps

Clone and install:

git clone https://github.com/yourusername/reddit-mcp-server.git
cd reddit-mcp-server
pip install -r requirements.txt

Configure environment:

cp .env.example .env
# Edit .env with your Reddit API credentials

Environment variables:

REDDIT_CLIENT_ID=your_reddit_client_id_here
REDDIT_CLIENT_SECRET=your_reddit_client_secret_here
REDDIT_USER_AGENT=RedditMCPServer/1.0.0
REDDIT_USERNAME=your_reddit_username_here
REDDIT_PASSWORD=your_reddit_password_here

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:

python simple_server.py

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

Read-only access: Cannot post, comment, or modify any Reddit content
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

reddit-mcp-server/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── .env.example          # Environment template
├── setup.py              # Package configuration
├── README.md             # Documentation
└── tests/                # Test suite (coming soon)

Running Tests

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

export MCP_DEBUG=1
python server.py

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

Built for the MCP community

Reddit MCP Server