5mghost-rover 0.0.3

Reddit MCP server — access Reddit data through MCP protocol

reddit-mcp

Reddit MCP server — access Reddit data (posts, comments, search) through the MCP protocol.

Quick Start

# 1. Full setup (OAuth login + Reddit cookies)
uvx --from 5mghost-rover reddit-mcp setup

# 2. Add to your AI client config (Claude Desktop, Cursor, etc.)

{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": ["--from", "5mghost-rover", "reddit-mcp", "serve"],
      "env": {
        "REDDIT_MCP_TOKEN": "pat_xxx"
      }
    }
  }
}

Authentication

reddit-mcp uses two layers of authentication:

1. PAT / OAuth token — Controls access to the MCP service (shared account system with yt-mcp / x-mcp)
2. Reddit cookies — Used to fetch data from Reddit's JSON API

PAT Setup (Simplest)

1. Visit https://mkterswingman.com/pat/login
2. Log in and generate a PAT
3. Set REDDIT_MCP_TOKEN=pat_xxx in your MCP config's env
4. Run uvx --from 5mghost-rover reddit-mcp setup-cookies to set up Reddit cookies

OAuth Setup (Full)

uvx --from 5mghost-rover reddit-mcp setup

This runs the OAuth flow and cookie setup in one step.

CLI Commands

Command	Description
reddit-mcp serve	Start MCP server (stdio transport)
reddit-mcp setup	Full setup: OAuth login + cookie setup
reddit-mcp setup-cookies	Cookie-only setup (already have a PAT)
reddit-mcp uninstall	Remove MCP registrations and local ~/.reddit-mcp config
reddit-mcp update	Check for updates and install latest version
reddit-mcp check	Check token & cookie status
reddit-mcp version	Show version

MCP Tools

Data Tools

• get_subreddit_posts — Get posts from a subreddit (hot/new/top/rising, up to 100 per request)
• get_post_content — Get a post's content and comment tree
• search_reddit — Search Reddit posts (global or within a subreddit)
• get_subreddit_info — Get subreddit metadata (subscribers, description, etc.)

Management Tools

• check_cookies — Check cookie validity, age, and username
• get_rate_limit_status — Check remaining API quota

Rate Limits

Reddit allows 100 requests per 10-minute window. The client automatically:

• Reads x-ratelimit-* headers from responses
• Throttles when remaining quota < 20
• Retries on 429 (Too Many Requests)

For typical usage (1-10 requests per conversation), you'll never hit the limit.

Cookie Management

Reddit cookies are stored at ~/.reddit-mcp/cookies.json (permissions: 600).

• Cookies are obtained by launching Chrome and having you log in to Reddit
• They're stored locally and never uploaded to any server
• If cookies expire (403 errors), run reddit-mcp setup-cookies to refresh
• A warning is shown when cookies are > 7 days old

Package Naming

The published PyPI package name is 5mghost-rover, and the installed executable is reddit-mcp.

• uvx --from 5mghost-rover reddit-mcp ... works for one-off runs
• pip install 5mghost-rover installs the reddit-mcp command globally

Requirements

• Python 3.10+
• Chrome browser (for setup / setup-cookies commands)
• A valid PAT or OAuth token

License

MIT