Reddit MCP Server

# 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](https://www.reddit.com/prefs/apps) - 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:** ```bash git clone https://github.com/yourusername/reddit-mcp-server.git cd reddit-mcp-server pip install -r requirements.txt ``` 2. **Configure environment:** ```bash cp .env.example .env # Edit .env with your Reddit API credentials ``` 3. **Environment variables:** ```env 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: ```bash 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 - **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 ```bash # Install development dependencies pip install -r requirements-dev.txt # Run tests pytest 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: ```bash 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](LICENSE) file for details. ## Support - **Issues**: [GitHub Issues](https://github.com/yourusername/reddit-mcp-server/issues) - **MCP Community**: [MCP Servers Directory](https://mcpservers.org) - **Reddit API**: [PRAW Documentation](https://praw.readthedocs.io/) ## Related Projects - [Model Context Protocol](https://modelcontextprotocol.io/) - [Claude Desktop](https://claude.ai/desktop) - [PRAW (Python Reddit API Wrapper)](https://github.com/praw-dev/praw) --- **Built for the MCP community**