Reddit Content API - Setup and Usage Guide

This project provides MCP (Model Context Protocol) tools for interacting with Reddit through Claude and Cursor.

Features

Reading trending posts from subreddits
Analyzing Reddit discussions with comments
Creating posts on Reddit
Adding comments to posts or replies to existing comments
Voting on posts and comments

Requirements

Python 3.10+
A Reddit account
A registered Reddit application (to obtain client_id and client_secret)
Virtual environment (venv or similar)
Claude Desktop and/or Cursor (optional but recommended)

Installation from Scratch

Follow these steps carefully to avoid import and configuration issues:

# 1. Clone the repository
git clone https://github.com/your-username/mcp-reddit.git
cd mcp-reddit

# 2. Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install dependencies (WITHOUT installing the package in editable mode)
pip install -r requirements.txt

# 4. Configure environment variables (see below)
# Create and edit the .env file

⚠️ IMPORTANT: DO NOT install the package in editable mode (pip install -e .)as it can cause module import problems.

Environment Configuration

Create a .env file in the project root with the following variables:

REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_REFRESH_TOKEN=your_refresh_token

To obtain a refresh token, run:

python -m mcp_reddit.auth_helper

Follow the instructions to authorize the application. The token will be automatically saved to the .env file.

Project Structure

mcp-reddit/
│
├── src/
│   └── mcp_reddit/
│       ├── __init__.py
│       ├── main.py           # Entry point for the MCP server
│       ├── reddit_fetcher.py # Implementation of Reddit tools
│       └── auth_helper.py    # Helper for generating authentication tokens
│
├── .env                      # Environment variables (create manually)
├── requirements.txt
├── setup.py
└── README.md

Running the Server Directly

To run manually (useful for development and testing):

cd /path/to/mcp-reddit
.venv/bin/python src/mcp_reddit/main.py

You should see logs indicating:

Server initialization
Reddit authentication verification
Registration of 10 tools (5 original + 5 with prefix)
"Running MCP server..."

Claude Desktop Configuration

Locate the configuration file:
- On macOS: /Users/your-username/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the configuration for reddit-content-api:

"reddit-content-api": {
  "command": "/full/path/to/mcp-reddit/.venv/bin/python",
  "args": [
    "-m",
    "mcp_reddit.main",
    "--stdio"
  ],
  "cwd": "/full/path/to/mcp-reddit",
  "env": {
    "PYTHONPATH": "/full/path/to/mcp-reddit/src:/full/path/to/mcp-reddit",
    "DEBUG": "true"
  }
}

⚠️ EXTREMELY IMPORTANT: PYTHONPATH must include both the src directory and the project root, in that order, separated by : (on Unix/macOS) or ; (on Windows)

Cursor Configuration

Locate the configuration file:
- On macOS: /Users/your-username/.cursor/mcp.json
- On Windows: %USERPROFILE%\.cursor\mcp.json
Add the same configuration as in Claude, adjusting paths as necessary.

Troubleshooting Common Issues

Issue: Only 2 tools appear instead of the expected 10

Symptoms: When running the server, only 2 tools appear instead of the expected 10.

Possible causes and solutions:

Import problem: Python is importing an installed version from site-packages instead of the local code in src/.

Solution:
- Make sure NOT to install the package in editable mode (pip install -e .)
- Explicitly add src to the beginning of PYTHONPATH in the configurations
- If you've already installed it, use pip uninstall reddit-content-api to remove it
Python cache: Old .pyc files can cause problems.

Solution:
- Remove all __pycache__ directories from the project
Version conflicts: Different versions of the same library.

Solution:
- Reinstall dependencies with pip install -r requirements.txt

Issue: "Cannot create post: Reddit authentication is not configured properly"

Cause: The refresh token is invalid or has expired.

Solution: Regenerate the token by running python -m mcp_reddit.auth_helper and make sure it's saved in .env.

Issue: Tools don't appear in Claude/Cursor

Cause: Incorrect configuration in the configuration files.

Solution:

Check paths and especially PYTHONPATH in the configuration files
Completely restart Claude/Cursor after modifying the configuration

Using the Tools in Claude/Cursor

Once configured, you can use the following tools:

mcp_reddit_content_api_fetch_reddit_hot_threads - Get trending posts
mcp_reddit_content_api_fetch_reddit_post_content - Analyze a post and its comments
mcp_reddit_content_api_create_reddit_post - Create a new post
mcp_reddit_content_api_add_reddit_comment - Add a comment
mcp_reddit_content_api_vote_on_reddit_content - Vote on content

Examples

Getting trending posts:

Subreddit: python
Number of posts: 5

Creating a post:

Subreddit: test
Title: Test from MCP
Content type: text
Content: This is a test from the Reddit Content API using MCP.

Contributions

If you find issues or have improvements, please create an issue or submit a pull request.

License

MIT

Support This Project

If you find this project useful in your work or research, please consider:

⭐ Starring the repository to show your support
🔄 Following the repository for updates on new features and improvements
🐛 Opening issues for bugs or feature requests
🛠️ Contributing with pull requests if you have improvements to share

Your support helps make this project better for everyone!

Reddit Content API - Setup and Usage Guide