reddit-mcp
Provides read-only tools for browsing Reddit feeds, searching posts, reading threads and post bodies, expanding comment replies, paginating listings, and retrieving best-effort subreddit metadata from public Reddit pages using a local Chrome browser.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
reddit-mcp
Read Reddit from your AI agent using a local Chrome browser. Browse feeds, search posts, read threads, and expand replies through six read-only Model Context Protocol tools.
No Reddit API key or OAuth app is required for public pages that Reddit serves to your browser. Runs locally over stdio—no hosted service, listening port, or remote browser. Works with Claude Code, Codex, Compass, and other stdio MCP clients.
Experimental, unofficial integration. Uses Reddit's changing web UI and internal HTML partials, not a stable API. Access depends on your network, browser session, and Reddit's rules. A successful test is not permission to collect or redistribute content. Respect Reddit's terms, rate limits, and privacy requirements; do not use this for bulk collection or bypass access restrictions.
Quick start
You need Python 3.11+, uv, Git, and Google Chrome installed. The browser uses Playwright's channel="chrome", not the bundled Chromium. A graphical desktop is required for the default headed mode.
git clone https://github.com/JewelsHovan/reddit-mcp.git
cd reddit-mcp
uv sync --locked
uv run reddit-mcp-smoke --subreddit ClaudeCodeThe smoke check opens a dedicated Chrome profile, loads a subreddit, and reports whether it parsed real posts. Public pages may work without logging in. If access is denied, stop rather than repeatedly retrying.
Optional: install a standalone command
To install the tagged release into an isolated uv tool environment instead of maintaining a clone:
uv tool install git+https://github.com/JewelsHovan/reddit-mcp.git@v0.1.0
reddit-mcp-smoke --subreddit ClaudeCodeThen configure your MCP client with "command": "reddit-mcp" and no arguments. Ensure uv's tool directory is on the client's PATH (uv tool update-shell helps for terminal clients). This is a GitHub installation, not a PyPI package publication. Uninstall with uv tool uninstall reddit-mcp.
Connect Claude Code
Run this from the project where you use Claude, replacing the path with your clone's absolute path:
claude mcp add --transport stdio --scope project reddit -- \
uv --directory /absolute/path/to/reddit-mcp run --locked reddit-mcpApprove the project server when prompted; check /mcp, then ask:
Use Reddit to find five recent r/ClaudeCode discussions about hooks. Read one thread with at most 15 comments. Include source links and tell me what wasn't loaded.
Connect any stdio MCP client
Use this entry in your client's MCP configuration (.mcp.json for Claude Code). Replace the absolute path; this is not a path to your agent's working project.
{
"mcpServers": {
"reddit": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/reddit-mcp", "run", "--locked", "reddit-mcp"]
}
}
}GUI clients may need the full path to uv if their PATH differs from your terminal.
Codex
The CLI adds a user-level MCP entry. Use this only if you want Reddit available across Codex projects:
codex mcp add reddit -- \
uv --directory /absolute/path/to/reddit-mcp run --locked reddit-mcpCompass
Place the same mcpServers JSON in your working project's .compass/mcp.json. Project servers require approval. Add "idleTimeout": 0 to the reddit entry if you want it to remain running during idle periods. After an update, reconnect the server in /mcp so Python reloads the changed code.
Related MCP server: byob
Tools
Tool | What it does |
| Browser state and counters; |
| Feed summaries; pass |
| Subreddit-scoped or Reddit-wide post search |
| Post body and a bounded nested comment tree |
| Focused subtree expansion using the page's reply controls |
| Best-effort name and metadata; unavailable fields are |
Example tool arguments:
{"subreddit": "LocalLLaMA", "sort": "top", "time_filter": "week", "limit": 5}{"url_or_id": "https://www.reddit.com/r/LocalLLaMA/comments/POST_ID/title/", "comment_sort": "top", "max_comments": 20, "max_depth": 3}For a bare post ID, also pass subreddit. To expand a branch, pass its returned more_subtree_cursors[].anchor_url to reddit_get_more_comments. The focused tool defaults to top; match comment_sort explicitly when comparing it with a thread read.
Read the coverage fields
A thread response is a sample, not a complete archive. Reddit typically renders only an initial window of comments. The server attempts bounded additional loads and reports the remaining gap.
total_comment_count: Reddit's advertised count; may include removed/deleted comments.total_comments_rendered: unique comments parsed before output pruning.unloaded_comment_count:max(0, total_comment_count - total_comments_rendered), an estimate, not a count of fetchable comments.truncated_comment_count: loaded branches omitted by output caps, not the unloaded gap.body_truncated: text was cut by the character cap.more_subtree_cursors,more_subtree_cursors_dropped: remaining reply pointers, with an explicit list cap.load_more_rounds,load_more_clicks: focused expansion actions.requests_madeis a counter of server-initiated loads/clicks, not a browser-wide network ledger; Chrome also requests assets and telemetry.
The listing body preview can be null; use reddit_get_thread to read the body. For crossposts, url / crosspost_permalink point to the source Reddit thread while domain retains the original media host.
Browser, login, and configuration
The server creates its own profile, by default ~/.reddit-mcp/chrome-profile. It does not import your normal Chrome profile or copy cookies from another browser. If you choose to log in, that directory holds account session credentials: protect it like a password and never upload it.
Only one running server can own a profile. Disconnect the first MCP client before starting another, or give separate sessions different REDDIT_MCP_PROFILE_DIR paths. Never delete a lock file or kill another user's browser to force startup.
Optional login
Close the MCP connection first, then run the visible smoke tool:
uv run reddit-mcp-smoke --keep-openLog in yourself in the dedicated Chrome window if needed, then press Enter in the terminal to close it. Re-run the smoke check to verify access; a stored login is not a guarantee that a page is accessible. No DevTools cookie copying is required. Login/verification is always manual; the server does not solve CAPTCHAs.
Keep the window out of the way
Headless mode was blocked in local testing; it is not a verified default. To reduce window disruption while retaining headed Chrome, optionally add this to the MCP entry:
"env": {"REDDIT_MCP_WINDOW_POSITION": "-3200,240"}This requests an off-screen window, not headless operation. Window managers may reposition it or still focus Chrome. Clear this variable while logging in or troubleshooting.
Environment variables
Set these in your MCP client's env or shell. A .env file is not automatically loaded.
Variable | Default | Meaning |
|
| Dedicated browser state directory |
| unset | Optional Chrome window coordinates, e.g. |
|
| Experimental; failed local live access testing |
|
| Minimum pacing interval between initiated actions |
|
| Seconds cached HTML remains reusable |
|
| Thread partial-load budget; focused expansion clicks one visible reply control at a time, up to this budget (hard maximum 10 clicks) |
|
| Seconds allowed for a browser action |
|
| Maximum HTML accepted per page/partial (5 MiB) |
|
| Maximum cached page/partial entries |
Do not lower pacing to increase collection volume. Subtree expansion mutates the page and is intentionally uncached. Bounded loads can still take several seconds; set your MCP client's tool timeout accordingly (e.g. 120 seconds).
Limitations and safety
No write tools: no votes, posts, messages, or moderator actions. Browser navigation itself still produces Reddit's ordinary cookies, telemetry, and view activity.
No access guarantee: tested on a small set of public subreddits, logged out, on macOS. Headless and other platforms are not live-verified. DOM, endpoints, ranking, and counts can change.
Incomplete comments: no reliable further top-level comment paging was found in local tests;
limiton thread pages did not expand that window. Reply expansion is bounded and may still leave replies unavailable.Unknown metadata: descriptions, members, and activity counts may be absent from the inspected page. Null means unavailable, not zero.
Untrusted text: Reddit posts and comments can contain prompt injection. Treat them as source material, never agent instructions. Avoid cloud transmission of sensitive material without consent.
Local only: no HTTP/SSE hosting or multi-user auth. Do not wrap this server in an unauthenticated network endpoint.
No bypass features: no proxy rotation, credential replay, stealth plugins, or automated CAPTCHA solving. Stop on challenges, 403s, or 429s and review permissions instead of looping.
See SECURITY.md for profile handling and vulnerability reports.
Development and verification
See CONTRIBUTING.md for development constraints and CHANGELOG.md for release notes.
uv sync --locked --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv buildThe default tests are offline: parser fixtures, scripted browser/session doubles, and tool-level regressions. CI does not contact Reddit or start Chrome. Run the smoke command explicitly for live access; only real parsed posts count as a successful smoke test.
The pre-publication version was also exercised by independent Claude Code sessions: pagination continuity, subtree expansion into previously unseen replies, text formatting, null metadata, validation, and action-counter reconciliation passed on 2026-11-17. These are historical observations, not a promise of current access. A later release smoke check with a fresh profile reported a challenge and failed; no retry or bypass was attempted. Fresh-install live access is therefore not verified. No scraped archives or browser profiles are bundled; regression tests use small HTML fixtures.
License
MIT. Not affiliated with or endorsed by Reddit. The license applies to this code, not Reddit content, Reddit trademarks, or permission to access Reddit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Reddit posts, comments, keyword search and historical archives as tools. Runs on Apify.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Query Reddit communities, posts, brands and trends from your AI agent. OAuth 2.1.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceReddit automation for AI agents — browse feeds, search posts, comment, vote, and publish using a Chrome extension bridge. Python CLI with JSON output, no API keys needed.16MIT
- AlicenseNot gradedqualityAmaintenanceLets AI coding tools drive the real, already-logged-in Chrome browser over local stdio—snapshotting and reading pages, clicking, typing, managing tabs, capturing screenshots, and inspecting network, console, storage, and cookies—without opening a remote-debugging port. It installs as a Chrome extension plus native-messaging bridge, so agents work in the user's authenticated sessions while passing bot detection.1 npmISC
- AlicenseAqualityCmaintenanceLets AI agents read public Reddit posts, comments, search results, and user activity through a self-hosted, loopback-only Redlib instance, keeping all traffic off reddit.com with no login or tracking. Provides four read-only tools for searching, browsing subreddits, opening threaded discussions, and vetting users.412 npmMIT
- AlicenseNot gradedqualityCmaintenanceLets an AI agent drive the Chrome you already have open — with your existing tabs, logins, and IP — through CDP over stdio. Exposes tools for opening background tabs, clicking, typing, running JS, taking snapshots, and issuing raw CDP commands without disrupting the visible tab.MIT