Reddit MCP Tool

A Model Context Protocol (MCP) server that provides read-only tools for browsing and searching Reddit content through Reddit’s official API. Built with FastMCP for seamless integration and automatic serialization. This server allows you to search for posts, read post details, and get subreddit information through MCP-compatible clients.

Features

• 🔍 Search Posts: Search for posts in specific subreddits with various sorting and filtering options
• 🌐 Site-wide Search: Search across all of Reddit with keyword queries
• 📊 Get Subreddit Info: Retrieve detailed information about subreddits
• 🔥 Get Hot Posts: Fetch hot posts from subreddits
• 📋 Get Post Details: Get comprehensive details about specific posts
• ⚡ FastMCP Integration: Built with FastMCP for automatic serialization and seamless MCP compatibility

Prerequisites

1. Python 3.10+ installed on your system
2. uv package manager installed (installation guide)
3. Reddit API credentials (see setup section below)

Reddit API Setup

1. Create a Reddit App:

   • Go to Reddit App Preferences
   • Click “Create App” or “Create Another App”
   • Choose “script” for the app type
   • Fill in the required fields:
     • Name: Your app name (e.g., “Reddit MCP Tool”)
     • Description: Brief description
     • About URL: Can be blank
     • Redirect URI: http://localhost:8080 (required but not used)

2. Get Your Credentials:

   • Client ID: Found under your app name (short string)
   • Client Secret: Found in the app details (longer string)

Installation

1. Clone or download this repository:

   git clone 
   cd reddit-mcp-tool
   

2. Install dependencies using uv:

   uv sync
   

3. Quick setup (recommended):

   uv run python scripts/setup.py
   

   This will create your .env file and show you what to do next.

4. Manual setup:

   cp env.example .env
   

   Edit the .env file with your Reddit API credentials:

   REDDIT_CLIENT_ID=your_client_id_here
   REDDIT_CLIENT_SECRET=your_client_secret_here
   REDDIT_USER_AGENT=reddit-mcp-tool:v0.2.0 (by /u/yourusername)
   

5. Test your setup:

   uv run python scripts/test_basic.py
   

   Note: This server operates in read-only mode and only requires the client ID, secret, and user agent for basic API access.

Troubleshooting

If you encounter issues, see TROUBLESHOOTING.md for detailed solutions to common problems.

Usage

Running the MCP Server

uv run reddit-mcp-tool

Or directly with Python:

uv run python -m reddit_mcp.server

Available Tools

1. Search Reddit Posts (Subreddit-specific)

Search for posts in a specific subreddit:

{
  "name": "search_reddit_posts",