Reddit MCP Server

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

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

1. Authentication

   • Login flow via CLI not yet implemented
   • Write tools require manually maintaining browser session with cookies
   • See #Future Work for planned auth flow

2. Error Handling

   • Limited retry logic for API failures
   • No built-in rate limit backoff (429 responses)
   • Timeouts could be more descriptive

3. Testing

   • Minimal unit test coverage
   • No integration tests with live Reddit API
   • Mock fixtures needed

4. 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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and test thoroughly
4. 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

• Model Context Protocol Docs
• Reddit JSON API
• FastMCP Documentation
• Playwright Documentation

---

Support

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

5. 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

6. 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