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 TheFoundersLogReplace
<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
.envfile. - 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 URLinclude_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 URLsort: "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 termssubreddit: 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
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
.envfile - 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
limitparameter in your requests - The server automatically handles most rate limiting scenarios
MCP connection issues:
- Verify the path to
server.pyin 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
Related Projects
Built for the MCP community