Skip to main content
Glama

Reddit MCP Tool

by GeLi2001
GitHub
Python
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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 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", "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

Featuresearch_reddit_postssearch_reddit_all
ScopeSingle subredditAll Reddit
Use CaseFocused community searchBroad topic discovery
ResultsFrom one subredditFrom multiple subreddits
Example"python" in r/programming"python" across all Reddit

Configuration

Environment Variables

VariableRequiredDescription
REDDIT_CLIENT_IDYesYour Reddit app's client ID
REDDIT_CLIENT_SECRETYesYour Reddit app's client secret
REDDIT_USER_AGENTYesUser agent string for API requests

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
Deploy Server
-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables browsing and searching Reddit content through read-only tools that access Reddit's official API. Supports searching posts, retrieving subreddit information, fetching hot posts, and getting detailed post information.

  1. Features
    1. Prerequisites
      1. Reddit API Setup
        1. Installation
          1. Troubleshooting
            1. Usage
              1. Running the MCP Server
              2. Available Tools
              3. Search Tool Comparison
            2. Configuration
              1. Environment Variables
            3. Integration with MCP Clients
              1. Claude Desktop Configuration
              2. Local Development Configuration
            4. Error Handling
              1. Rate Limiting
                1. Development
                  1. Running Tests
                  2. Code Formatting
                2. Contributing
                  1. License
                    1. Disclaimer
                      1. Notes

                        Related MCP Servers

                        • Wikimedia MCP Server

                          privetin
                          -
                          security
                          A
                          license
                          -
                          quality
                          Enables programmatic interaction with Wikimedia APIs, offering features like searching content, retrieving page information, and accessing historical events across multiple languages.
                          Last updated -
                          2
                          MIT License
                          • Apple

                        • MCP Server Reddit

                          Hawstein
                          A
                          security
                          A
                          license
                          A
                          quality
                          A server allowing interaction with Reddit via the public API, enabling browsing frontpage posts, retrieving subreddit details, and reading post comments through a Model Context Protocol.
                          Last updated -
                          8
                          96
                          MIT License
                          • Apple
                          • Linux

                        • DuckDuckGo Web Search MCP Server

                          kouui
                          A
                          security
                          F
                          license
                          A
                          quality
                          Allows you to search the web using DuckDuckGo and optionally fetch and summarize content from search results.
                          Last updated -
                          2
                          3

                        • LinkedIn Profile Analyzer MCP

                          Hama-amir
                          -
                          security
                          A
                          license
                          -
                          quality
                          Enables users to fetch, analyze, and manage LinkedIn posts data through tools that retrieve profiles, search posts by keywords, filter by date, and identify top-performing content based on engagement metrics.
                          Last updated -
                          MIT License

                        View all related MCP servers

                        New MCP Servers

                        MCP directory API

                        We provide all the information about MCP servers via our MCP API.

                        curl -X GET 'https://glama.ai/api/mcp/v1/servers/GeLi2001/reddit-mcp'

                        If you have feedback or need assistance with the MCP directory API, please join our Discord server