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

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