# 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**
   ```bash
   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:
   ```bash
   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

```bash
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:

```json
{
  "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.