5mghost-rover 0.0.14

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

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

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

# 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

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 (Simplest)

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 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 [--shutdown-browser]	Full setup: OAuth login + cookie setup
reddit-mcp setup-cookies [--shutdown-browser]	Cookie-only setup (already have a PAT)
reddit-mcp uninstall	Remove MCP registrations and local ~/.mkterswingman/reddit-mcp config
reddit-mcp update	Check for updates and install latest version
reddit-mcp install-skills	Install/update bundled use-reddit-mcp skill in local AI clients
reddit-mcp check	Check token & cookie status
reddit-mcp version	Show version

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).

• Cookie setup/import always works on a copied local browser profile (Chrome/Edge/Chromium), never on your live browser process
• If a reusable Reddit session already exists in local browser profiles, setup-cookies imports it headlessly
• If no reusable session is found, setup-cookies asks you to log in from your normal local browser profile and waits to import that session automatically
• On Windows, if browser profile files are locked, save unfinished work in Chrome or Edge, then rerun with --shutdown-browser to let reddit-mcp try to close Chrome and Edge before importing cookies
• They're stored locally and never uploaded to any server
• If cookies expire (403 errors), reddit-mcp first tries headless re-import from local profiles; 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.

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

Requirements

• Python 3.11+
• Playwright browser runtime (run playwright install chromium once if missing)
• A valid PAT or OAuth token

Verification

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

License

MIT