Reddit MCP Server

How to use

You use this MCP server by connecting it to an MCP client that supports stdio endpoints. Start the local Reddit MCP server via Docker, then configure your client to run the server as an MCP endpoint. Once connected, you can search specific subreddits, fetch post details and comments, and browse hot posts. The available tools expose these capabilities and you can invoke them through your MCP client’s tool interface. When you request information, the client will relay your prompts to the server and return Reddit results for you to analyze.

How to install

Prerequisites you need before installation:

- Docker (required)

- Python 3.12+ (for local development and testing)

- Reddit API credentials (client ID, client secret, and a user agent)

Step-by-step commands to get started locally

# Install Docker Desktop for your platform if you don’t have it yet
# Ensure Docker is running and accessible

docker --version

docker run hello-world  # test that Docker can pull and run containers

# Obtain Reddit API credentials from Reddit (client_id, client_secret, user_agent) and export them as environment variables
# Replace placeholders with your actual values
export REDDIT_CLIENT_ID=YOUR_CLIENT_ID
export REDDIT_CLIENT_SECRET=YOUR_CLIENT_SECRET
export REDDIT_USER_AGENT=YOUR_USER_AGENT

# Build the Reddit MCP server image (if you have a Dockerfile configured for this project)
docker build -t mcp-reddit .

# Run the server locally (example using the official image name shown in inline examples)
docker run -i --rm \
  -e REDDIT_CLIENT_ID=$REDDIT_CLIENT_ID \
  -e REDDIT_CLIENT_SECRET=$REDDIT_CLIENT_SECRET \
  -e REDDIT_USER_AGENT=$REDDIT_USER_AGENT \
  ghcr.io/nangeplus/mcp-reddit:latest

# Alternatively, if you directly start from a server script locally (no Docker)
# Navigate to the project directory and run:
python src/server.py

Additional sections

Configuration and usage notes are important to ensure smooth operation and security. Keep your Reddit API credentials private and avoid embedding them directly in files. Use environment variables to provide sensitive values. Reddit API usage is rate-limited, so plan your queries accordingly. If you are using the Docker-based workflow, ensure the container has access to the required environment variables and that you’re pulling the correct image version.

Security and best practices - Store Reddit API credentials securely and rotate them periodically. - Do not expose credentials in shared or public environments. - Use environment variables rather than hard-coded values. - Monitor logs for unusual activity and respect Reddit’s API rate limits.

Local development steps you can follow
- Clone the repository and open a terminal in the project directory.
- Install Python dependencies if you plan to run locally: `pip install -r requirements.txt`.
- Start the server locally with `python src/server.py` to verify it runs without Docker.
- Build and run the Docker image if you prefer containerized execution: `docker build -t mcp-reddit .` and `docker run -i --rm -e REDDIT_CLIENT_ID=YOUR_CLIENT_ID -e REDDIT_CLIENT_SECRET=YOUR_CLIENT_SECRET -e REDDIT_USER_AGENT=YOUR_USER_AGENT mcp-reddit`.

Notes on usage with MCP clients

Your MCP client should pass tool invocations to the Reddit MCP server and display results. The server exposes tools for searching subreddits, getting post details, and listing hot posts, which you can call from your client’s tool interface. Remember to supply the required arguments for each tool, such as subreddit names, post IDs, and result limits.

search_subreddit

Search posts within a specific subreddit using a query and limit the number of results returned.

get_post_details

Fetch detailed information for a given Reddit post ID, including comments up to a specified limit.

get_subreddit_hot

Retrieve a list of hot posts from a subreddit, limited by a maximum number of items.