5mghost-rover

reddit-mcp

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

Quick Start

# One-line installer (macOS / Linux)
curl -fsSL https://mkterswingman.com/install/reddit-mcp.sh | bash

# One-line installer (Windows PowerShell)
irm https://mkterswingman.com/install/reddit-mcp.ps1 | iex

# Direct install without hosted installer
uv tool install 5mghost-rover

# Full setup (auth + Reddit cookies + AI client registration)
reddit-mcp setup

Add this runtime command to AI clients that need manual config:

{
  "mcpServers": {
    "reddit-mcp": {
      "command": "reddit-mcp",
      "args": ["serve"]
    }
  }
}

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

First-party local MCPs on the same machine now share one auth file at ~/.mkterswingman/auth.json. That means logging into yt-mcp or another first-party local MCP can satisfy reddit-mcp too. Reddit local state now lives under ~/.mkterswingman/reddit-mcp/.

PAT Setup

1. Visit https://mkterswingman.com/pat/login
2. Log in and generate a PAT
3. Either save it once through any first-party local MCP setup flow, or set REDDIT_MCP_TOKEN=pat_xxx in your MCP config's env
4. Run reddit-mcp setup-cookies to set up Reddit cookies

Full Setup

reddit-mcp setup

This runs auth, cookie setup, AI client registration, and final verification in one flow.

CLI Commands

Bundled Skill

The package includes a bundled skill use-reddit-mcp that helps AI clients route Reddit analysis requests to the right tools.

• setup installs the skill automatically
• update refreshes the installed skill
• You can manually run reddit-mcp install-skills at any time

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 ~/.mkterswingman/reddit-mcp/cookies.json (permissions: 600).

• On macOS, setup-cookies first tries to import a reusable Reddit session from copied local Chrome / Edge profiles
• On Windows, Chromium now protects cookies from cross-profile reuse, so setup-cookies opens your installed Chrome / Edge executable with a dedicated reddit-mcp browser profile stored at ~/.mkterswingman/reddit-mcp/browser-profile
• The Windows guided login flow avoids depending on your live Chrome / Edge profile state while still using a real local browser that Reddit accepts for interactive login
• They're stored locally and never uploaded to any server
• If cookies expire (403 errors), reddit-mcp first tries a silent refresh path; if that fails, run reddit-mcp setup-cookies manually
• A warning is shown when cookies are close to expiry (or fallback age is very old)

Package Naming

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

• Supported install path: uv tool install 5mghost-rover
• Supported runtime command: reddit-mcp serve
• Supported setup entrypoint: reddit-mcp setup

Requirements

• uv (the hosted installer can install it automatically)
• On Windows, a local Google Chrome or Microsoft Edge installation for interactive cookie setup
• A valid PAT or OAuth token

You do not need to preinstall Python when using the supported uv path.

Troubleshooting

• If reddit-mcp setup fails during auth, visit https://mkterswingman.com/pat/login and retry.
• If no AI client is auto-detected, keep using reddit-mcp serve as the manual MCP command.
• If cookies expire or Reddit starts returning 403s, rerun reddit-mcp setup-cookies.

Verification

• Run python3 -m pytest for the normal automated suite
• Run docs/E2E_CHECKLIST.md before releasing install or cookie-flow changes

License

MIT