reddit-lyr

An async Reddit API wrapper and MCP server for AI agents — 50+ typed endpoints, zero PRAW dependency, and a 32-tool agent interface for browsing, posting, commenting, voting, moderating, and searching through the same session your browser has.

pipx install reddit-lyr

---

---

What it is

• Page index — every active doc and the question it owns.

Layer	Description
Core	RedditClient — async, typed, 50+ endpoints
MCP Server	32 tools for agents (browse, post, comment, vote, mod)
CLI	reddit-lyr browse, reddit-lyr post, reddit-lyr inbox

Endpoints: Frontpage, Subreddits, Posts, Comments, Users, Messages, Moderation, Search, Wiki, Live, Collections, Awards, Polls, Predictions

---

Quick start

# Install


pipx install reddit-lyr

# Auth (interactive)
reddit-lyr auth login

# Use as library
from reddit_httpx import RedditClient
client = RedditClient()
posts = await client.browse_subreddit("rust", sort="hot", limit=25)

# MCP server for agents
reddit-lyr mcp

Multiple accounts

reddit-lyr supports any number of named accounts, each with an isolated cookie store under ~/.reddit-lyr/accounts/<name>/. The default account (the legacy top-level ~/.reddit-lyr/cookies.json) keeps working unchanged for every existing workflow.

# List accounts
reddit-lyr --accounts

# Register a new account (import its cookies once)
REDDIT_ACCOUNT=workmode reddit-lyr --cookies-file workmode-cookies.json

# Operate on it — the flag works before any tool name
reddit-lyr --account workmode --status
reddit-lyr --account workmode browse_subreddit rust --limit 5
REDDIT_ACCOUNT=workmode reddit-lyr mcp   # or via env, for MCP/cron contexts

# Logout only that account
reddit-lyr --account workmode --logout

Non-interactive contexts (MCP servers, cron jobs) select the account via the REDDIT_ACCOUNT environment variable. The shared Obscura cookie daemon is automatically bypassed for non-default accounts — it caches one session per platform and has no account awareness, so it is never allowed to serve a named account's requests.

---

MCP Tools (32)

Category	Tools
Browse	browse_frontpage, browse_popular, browse_subreddit, get_post, get_comments
Post	submit_text, submit_link, edit_post, delete_post
Comment	comment, reply, edit_comment, delete_comment
Vote	vote_post, vote_comment
Message	get_inbox, send_message, mark_read
User	get_profile, get_karma, get_saved
Mod	mod_approve, mod_remove, mod_lock, mod_sticky
Search	search_posts, search_subreddits, search_users

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    RedditClient                               │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │  Auth    │  │  Models  │  │  Endpoints│  │  MCP     │     │
│  │  (OAuth) │  │  (Pydantic)│  │  (50+)   │  │  Server  │     │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘     │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
           httpx.AsyncClient
           (connection pool, retry, timeout)

---

Example: Agent browsing Reddit

# Agent uses MCP tools:
# 1. browse_subreddit("MachineLearning", sort="hot", limit=10)
# 2. get_post("t3_abc123") → full post + comments
# 3. search_posts("transformer architecture", subreddit="MachineLearning")
# 4. submit_text("r/MySub", "Title", "Body") — with auth

---

Visual proof

MCP tools	Comment tree	Post detail

Search results	Mod tools	Message inbox

Requirements

• Python 3.11+
• Reddit app credentials (client_id, client_secret)

---

Limitations

Capability	Status
Submit text/link/comment posts, delete own posts, reply	🟢 working (verified live)
Vote / mod tools / search / posts / comments reads	🟢 working
send_message (private message)	🔴 hard 401 on /api/compose — Reddit api/compose rejects every auth scheme tried (modhash param, X-Modhash header, Bearer token_v2) even though submit/read/delete work with the same session. Endpoint-level auth gating, not a tool bug.

Notes:

• Cookie resolution order: obscura daemon (port 9999) → local file → browser re-extraction. A dead daemon adds latency before the file fallback is reached. The on-disk cookie file must stay single-wrap {"cookies": {flat}}; nested wraps read as empty and block authed tools.

---

Related CLI Tools

This project is part of a family of agent-friendly CLI tools for social platforms:

Tool	CLI	Repo
Instagram	instagram-lyr	ishan-parihar/instagram-lyr
Reddit	reddit-lyr	ishan-parihar/reddit-lyr
LinkedIn	linkedin-lyr	ishan-parihar/linkedin-lyr
Twitter/X	twitter-lyr	ishan-parihar/twitter-lyr
Discord	discord	ishan-parihar/discord-cli
Telegram	tg	ishan-parihar/tg-cli

---

License

MIT — see LICENSE.

---

☕ Support & Sponsorship

If you find this project useful, consider supporting ongoing development:

Your support funds new features, releases, and infrastructure for the whole ecosystem.

Updating

Use reddit-lyr update --check to check without changing the installation, or reddit-lyr update to update it. reddit-lyr upgrade is an alias. The command delegates to the manager that owns this installation (uv, pipx, or pip) and refuses editable, local-checkout, system, or unknown installs instead of replacing package-manager-owned files. For example: uv tool upgrade reddit-lyr.