Reddit MCP Server

A Model Context Protocol (MCP) server that provides atomic tools for interacting with Reddit's API. This server enables AI agents to search, read, and analyze Reddit content through natural language commands.

Features

• Search Reddit posts by keywords, subreddits, and time periods
• Get post details including comments, scores, and metadata
• List subreddits with trending topics and community information
• Get user profiles and their recent activity
• Search comments across Reddit
• Get trending posts from specific subreddits

Installation

Prerequisites

• Python 3.8 or higher
• Reddit API credentials (Client ID and Client Secret)

Setup

1. Clone or download this repository

2. Install dependencies

   pip install -r requirements.txt
   

3. Get Reddit API Credentials

   To use this MCP server, you need to create a Reddit application:

   1. Go to https://www.reddit.com/prefs/apps
   2. Click "Create App" or "Create Another App"
   3. Select "script" as the application type
   4. Fill in the required fields:
      • Name: Your app name (e.g., "MCP Reddit Server")
      • Description: Brief description
      • About URL: Can be left blank
      • Redirect URI: Use http://localhost:8080 (not actually used for script apps)
   5. Click "Create App"
   6. Note down your Client ID (the string under your app name) and Client Secret

4. Configure Environment Variables

   Create a .env file in the project root or set these environment variables:

   export REDDIT_CLIENT_ID="your_client_id_here"
   export REDDIT_CLIENT_SECRET="your_client_secret_here"
   export REDDIT_USER_AGENT="MCP_Reddit_Server/1.0 (by /u/your_username)"
   

Usage

Running the Server

python reddit_mcp_server.py

The server will start on localhost:8080 by default.

Connecting to an MCP Client

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "reddit": {
      "command": "python",
      "args": ["/path/to/reddit_mcp_server.py"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USER_AGENT": "MCP_Reddit_Server/1.0"
      }
    }
  }
}

Available Tools

search_reddit_posts

Search for posts across Reddit or within specific subreddits.

Parameters:

• query (string, required): Search terms
• subreddit (string, optional): Limit search to specific subreddit
• limit (integer, optional): Number of results (default: 10, max: 100)
• time_filter (string, optional): Time period (hour, day, week, month, year, all)

Example Usage:

• "Search for posts about Python programming"
• "Find recent posts about machine learning in r/MachineLearning"
• "Get the top 20 posts about AI from the past week"

get_post_details

Get detailed information about a specific Reddit post.

Parameters:

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

Example Usage:

• "Get details for post t3_abc123"
• "Show me the full post and comments for https://reddit.com/r/Python/comments/abc123"

list_subreddits

Get information about subreddits, including trending topics.

Parameters:

• query (string, optional): Search for specific subreddits
• limit (integer, optional): Number of results (default: 10)

Example Usage:

• "List popular programming subreddits"
• "Find subreddits about data science"

get_user_profile

Get information about a Reddit user and their recent activity.

Parameters:

• username (string, required): Reddit username

Example Usage:

• "Get profile for user u/spez"
• "Show me the recent posts by u/username"

search_comments

Search for comments across Reddit.

Parameters:

• query (string, required): Search terms
• subreddit (string, optional): Limit search to specific subreddit
• limit (integer, optional): Number of results (default: 10)

Example Usage:

• "Search for comments about React hooks"
• "Find comments about Docker in r/docker"

get_trending_posts

Get trending posts from a specific subreddit.

Parameters:

• subreddit (string, required): Subreddit name (without r/)
• limit (integer, optional): Number of results (default: 10)
• time_filter (string, optional): Time period (hour, day, week, month, year, all)

Example Usage:

• "Get trending posts from r/Python"
• "Show me the top posts from r/technology this week"

Error Handling

The server includes robust error handling for:

• Invalid API credentials
• Rate limiting (Reddit API has rate limits)
• Network connectivity issues
• Invalid parameters
• Missing or malformed responses

All errors are returned with clear, actionable messages that help the AI understand what went wrong and potentially self-correct.

Rate Limiting

Reddit's API has rate limits:

• 60 requests per minute for authenticated requests
• The server automatically handles rate limiting and will retry requests when possible

Security Notes

• Never commit your Reddit API credentials to version control
• Use environment variables for all sensitive configuration
• The server only makes read-only requests to Reddit's API
• No user authentication is required for public data access

Contributing

This MCP server follows the Klavis AI development guidelines:

• Atomic, single-purpose tools
• Clear, descriptive tool names and descriptions
• Comprehensive error handling
• User-centric design for AI agents

License

This project is part of the Klavis AI MCP server collection.