Reddit MCP Server

Enterprise-grade Model Context Protocol (MCP) server for seamless Reddit data access. Enables AI agents and developers to search, monitor, and analyze Reddit's 73M daily active users and 100K+ communities.

Features (MVP v0.1.0)

• search_reddit - Search all of Reddit or specific subreddits with filters
• get_subreddit_posts - Monitor subreddits for hot, new, top, or rising posts
• get_post_comments - Retrieve nested comment threads with full context
• get_trending_topics - Discover trending keywords and topics in real-time

All tools include intelligent Redis caching (75%+ hit rate) and automatic rate limiting.

Prerequisites

• Python 3.11 or higher
• Redis server (local or cloud)
• Reddit API credentials (client ID and secret)

Getting Reddit API Credentials

1. Go to https://www.reddit.com/prefs/apps
2. Click "Create App" or "Create Another App"
3. Select "script" as the app type
4. Fill in the required fields:
   • Name: "Reddit MCP Server"
   • Redirect URI: http://localhost:8080
5. Save your client ID (under the app name) and client secret

Local Development Setup

1. Clone and Install

# Clone the repository
cd /Users/padak/github/apify-actors

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment Variables

Create a .env file in the project root:

# Reddit API Credentials
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here

# Redis Connection
REDIS_URL=redis://localhost:6379

# Logging (optional)
LOG_LEVEL=INFO

3. Start Redis (Local)

# Using Docker
docker run -d -p 6379:6379 redis:7-alpine

# Or install Redis locally (macOS)
brew install redis
brew services start redis

4. Run the Server

python -m src.main

The MCP server will start in standby mode on the configured port (default: /mcp endpoint).

Testing

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=src tests/

# Run only unit tests
pytest tests/unit/

# Run only integration tests (requires Redis + Reddit API)
pytest tests/integration/

Apify Deployment

Deploy to Apify Platform

1. Install Apify CLI

npm install -g apify-cli
apify login

2. Configure Secrets

In the Apify Console, add these secrets to your Actor:

• REDDIT_CLIENT_ID
• REDDIT_CLIENT_SECRET
• REDIS_URL

3. Deploy

apify push

The Actor will be deployed in standby mode and accessible via the MCP endpoint.

Environment Variables (Apify)

Variable	Type	Required	Description
REDDIT_CLIENT_ID	Secret	Yes	Reddit API client ID
REDDIT_CLIENT_SECRET	Secret	Yes	Reddit API client secret
REDIS_URL	String	Yes	Redis connection URL
LOG_LEVEL	String	No	Logging level (default: INFO)

Project Structure

/Users/padak/github/apify-actors/
├── src/
│   ├── main.py              # Entry point
│   ├── tools/               # MCP tool implementations
│   ├── reddit/              # Reddit API integration
│   ├── cache/               # Redis caching layer
│   ├── models/              # Pydantic data models
│   └── utils/               # Shared utilities
├── tests/                   # Test suite
├── docs/                    # Documentation
├── actor.json               # Apify Actor configuration
├── Dockerfile               # Container definition
├── requirements.txt         # Python dependencies
└── README.md                # This file

Development Workflow

Code Quality

# Format code with Black
black src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type check with mypy
mypy src/ --strict

Running Individual Tools (Development)

TODO: Add examples once tools are implemented (MVP-006 through MVP-009)

Architecture

• MCP Server: FastMCP framework for JSON-RPC protocol handling
• Reddit API: PRAW (Python Reddit API Wrapper) for authenticated access
• Caching: Redis with intelligent TTL policies (2min - 1hr)
• Rate Limiting: Token bucket algorithm (100 requests/min)
• Data Validation: Pydantic models for type-safe inputs/outputs

See /Users/padak/github/apify-actors/docs/architecture/ for detailed technical documentation.

Troubleshooting

Redis Connection Errors

# Check if Redis is running
redis-cli ping
# Should return: PONG

# Test connection with URL
redis-cli -u redis://localhost:6379 ping

Reddit API Authentication Errors

• Verify your client ID and secret are correct
• Check that your Reddit app type is "script"
• Ensure the redirect URI matches: http://localhost:8080

Import Errors

# Ensure you're in the virtual environment
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Contributing

This is an MVP project. Contributions should align with the roadmap:

• MVP (Week 1-2): Core 4 tools + caching + rate limiting
• v1.0 (Week 3-4): Monetization, sentiment analysis, user auth
• v2.0 (Month 2+): Write operations, real-time monitoring, analytics

Documentation

• Product Requirements (PRD)
• Architecture Overview
• Epic Stories

License

[Add license information]

Support

For issues or questions, please refer to the documentation in /docs/ or create an issue in the repository.

---

Status: MVP v0.1.0 (Week 1-2 Development) Target: 5,000 MAU by Month 6 (Apify $1M Challenge)