GeLi2001/reddit-mcp

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 <repository-url>
   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 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",
  "arguments": {
    "subreddit": "python",
    "query": "machine learning",
    "limit": 10,
    "sort": "relevance",
    "time_filter": "week"
  }
}

Parameters:

• subreddit (required): The subreddit name (without r/)
• query (required): Search query string
• limit (optional): Number of posts to return (1-100, default: 10)
• sort (optional): Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance")
• time_filter (optional): Time filter - "all", "day", "week", "month", "year" (default: "all")

2. Search All Reddit (Site-wide)

Search across all of Reddit:

{
  "name": "search_reddit_all",
  "arguments": {
    "query": "artificial intelligence",
    "limit": 20,
    "sort": "top",
    "time_filter": "week"
  }
}

Parameters:

• query (required): Search query string
• limit (optional): Number of posts to return (1-100, default: 10)
• sort (optional): Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance")
• time_filter (optional): Time filter - "all", "day", "week", "month", "year" (default: "all")

3. Get Post Details

Get detailed information about a specific post:

{
  "name": "get_reddit_post_details",
  "arguments": {
    "post_id": "abc123"
  }
}

Parameters:

• post_id (required): The Reddit post ID

4. Get Subreddit Information

Get information about a subreddit:

{
  "name": "get_subreddit_info",
  "arguments": {
    "subreddit": "python"
  }
}

Parameters:

• subreddit (required): The subreddit name (without r/)

5. Get Hot Posts

Get hot posts from a subreddit:

{
  "name": "get_hot_reddit_posts",
  "arguments": {
    "subreddit": "programming",
    "limit": 15
  }
}

Parameters:

• subreddit (required): The subreddit name (without r/)
• limit (optional): Number of posts to return (1-100, default: 10)

Search Tool Comparison

Configuration

Environment Variables

Integration with MCP Clients

This server implements the Model Context Protocol and can be used with any MCP-compatible client. Configure your MCP client to connect to this server using stdio transport.

Claude Desktop Configuration

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "reddit-mcp-tool": {
      "command": "uvx",
      "args": ["reddit-mcp-tool@latest"],
      "env": {
        "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)"
      }
    }
  }
}

Local Development Configuration

For local development, use:

{
  "mcpServers": {
    "reddit-mcp-tool": {
      "command": "uv",
      "args": ["run", "reddit-mcp-tool"],
      "cwd": "/path/to/reddit-mcp-tool",
      "env": {
        "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)"
      }
    }
  }
}

Error Handling

The server includes comprehensive error handling for common scenarios:

• Invalid subreddit names
• Post not found
• Authentication failures
• Rate limiting
• Network errors

All errors are returned as descriptive text content through the MCP protocol.

Rate Limiting

Reddit's API has rate limits. The server respects these limits, but you may encounter rate limiting errors if you make too many requests in a short period. The default rate limit for authenticated users is typically 60 requests per minute.

Development

Running Tests

uv run pytest

Code Formatting

uv run black .
uv run ruff check .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License. See LICENSE file for details.

Disclaimer

This tool is for educational and development purposes. Please ensure you comply with Reddit's API Terms of Service and community guidelines when using this tool. This is a read-only tool that respects Reddit's API limits and does not provide any posting or commenting capabilities.

Notes

• This project was renamed to reddit-mcp-tool to avoid conflicts with the existing reddit-mcp package on PyPI
• Only read-only operations are supported (search, read posts, get subreddit info)
• No user authentication is required - only app credentials for basic API access
• Built with the reliable PRAW (Python Reddit API Wrapper) library
• Includes proper rate limiting and error handling