Reddit MCP Server

A Model Context Protocol (MCP) server for querying Reddit data and posting content. Built for AI agents and LLM-powered applications.

License: MIT

Overview

The Reddit MCP Server enables LLM applications to:

Read public Reddit data (posts, comments, user profiles) via efficient JSON parsing
Write authenticated content (post replies) using Playwright browser automation
Search subreddits with filtering, sorting, and pagination
Validate input to prevent injection attacks

Perfect for AI research tools, content analysis systems, and bot development.

Quick Start

1. Installation

# Clone the repository
git clone https://github.com/ajaaysrinivaas/reddit_mcp.git
cd reddit_mcp

# Install dependencies
pip install -e .

Requirements: Python 3.12+

2. Start the Server

# Default stdio transport (recommended for MCP clients)
reddit-mcp-server

# Alternative transports
reddit-mcp-server --transport http          # HTTP server
reddit-mcp-server --transport sse           # Server-Sent Events

3. Use in Your Application

See API Documentation for complete tool reference.

Example: Query a subreddit

# Via MCP client
result = await client.call_tool("get_subreddit_posts", {
    "subreddit": "Python",
    "category": "hot",
    "limit": 10
})

Features

🔍 Read Tools (Public API)

search_subreddit — Full-text search within communities
get_subreddit_posts — Fetch trending, new, rising, or top posts
get_post_thread — Retrieve post + comments (threaded view)
get_user_profile — User karma, account age, public info
get_user_activity — Recent posts & comments from a user

✍️ Write Tools (Authenticated)

post_reply — Reply to threads or comments (requires authentication)

⚡ Technical Highlights

Efficient JSON parsing — Strips verbose Reddit API responses down to LLM-relevant fields
Input validation — Regex-based protection against injection attacks
Multiple transports — stdio, HTTP, SSE, and streamable-HTTP support
Zero external dependencies for reads — Uses only aiohttp for API calls
Browser automation — Playwright for authenticated write operations

Installation Options

Option A: Development Install (Editable)

pip install -e .

Changes to source code immediately reflected without reinstalling.

Option B: Standard Install

pip install .

Option C: With Development Dependencies

pip install -e ".[dev]"  # If dev extras defined in pyproject.toml

Configuration

Environment Variables

Create a .env file (see .env.example if available):

# Optional: Reddit authentication (for write tools)
REDDIT_USERNAME=your_username
REDDIT_PASSWORD=your_password

# Optional: Browser automation settings
BROWSER_HEADLESS=true
BROWSER_TIMEOUT=30000

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop, VS Code):

{
  "mcpServers": {
    "reddit": {
      "command": "reddit-mcp-server",
      "args": ["--transport", "stdio"]
    }
  }
}

Architecture

reddit_mcp_server/
├── server.py              # FastMCP server initialization & lifecycle
├── cli_main.py            # Command-line entry point
├── http_client.py         # Shared aiohttp session for Reddit API
├── drivers/
│   └── browser.py         # Playwright browser automation for auth write ops
└── tools/
    ├── read_tools.py      # Public API read operations
    └── write_tools.py     # Authenticated write operations

API Documentation

For complete parameter descriptions, response schemas, and examples, see API.md.

Quick Reference

Tool	Parameters	Returns
`search_subreddit`	subreddit, query, sort, time_filter, limit	Array of posts
`get_subreddit_posts`	subreddit, category, limit	Array of posts
`get_post_thread`	post_id, comment_limit, sort	{ post, comments }
`get_user_profile`	username	User profile object
`get_user_activity`	username, activity_type, limit	Array of posts/comments
`post_reply`	url_or_id, content	Reply object

Known Limitations

⚠️ Current Gaps

Authentication
- Login flow via CLI not yet implemented
- Write tools require manually maintaining browser session with cookies
- See #Future Work for planned auth flow
Error Handling
- Limited retry logic for API failures
- No built-in rate limit backoff (429 responses)
- Timeouts could be more descriptive
Testing
- Minimal unit test coverage
- No integration tests with live Reddit API
- Mock fixtures needed
Performance
- No client-side rate limiting
- May hit Reddit's API throttling at scale

Development

Project Structure

reddit_mcp_server/ — Main package
- server.py — FastMCP server setup
- tools/ — Tool implementations
- drivers/ — Browser automation
tests/ — Test suite (in progress)
API.md — Full API documentation
pyproject.toml — Project metadata and dependencies

Running Locally

# Install in editable mode
pip install -e .

# Start server
reddit-mcp-server --transport stdio

# In another terminal, test with curl (HTTP transport):
curl -X POST http://localhost:5000/tools/get_subreddit_posts \
  -H "Content-Type: application/json" \
  -d '{"subreddit": "python", "limit": 5}'

Contributing

We welcome contributions! To get started:

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Make your changes and test thoroughly
Submit a pull request with a clear description

Areas for contribution:

Test coverage (unit and integration)
Authentication flow implementation
Rate limiting and retry logic
Documentation improvements

Troubleshooting

Server won't start

# Verify Python version
python --version  # Should be 3.12+

# Check if dependencies installed
pip list | grep fastmcp

# Reinstall if needed
pip install -e . --force-reinstall

Tools not appearing in MCP client

Ensure .vscode/mcp.json has correct path (see Configuration)
Restart your MCP client after changes
Check server logs for startup errors

Write tools failing

Verify browser automation tools installed: python -m playwright install
Check .env credentials are correct
Ensure authenticated session is active

License

MIT License — see LICENSE file for details.

Resources

Support

Issues: GitHub Issues
Questions: Open a discussion or check existing issues
Feedback: PRs and suggestions welcome!

Session Persistence — Browser state not persisted
- Browser sessions are ephemeral; login doesn't persist across server restarts
- Need to save/load browser cookies from disk
Comprehensive Validation — Limited input validation
- Only subreddit/username validated; comment IDs, URLs not fully validated
- Could add stricter type checking

Development

Running Tests

python -m pytest test_server.py

Building the Package

uv build
# or
python -m build

License

MIT