A Model Context Protocol server that lets AI assistants explore Reddit trends,
discover communities, and analyze what's hot — without authentication.
What it does • Getting Started • Tools • Trend Score • JQ Filters • Docker
This MCP gives your AI assistant the ability to:
- Discover which subreddits are most relevant for any topic
- Find crossover communities that cover multiple topics at once
- Track what's trending right now across specific subreddits
- Search posts globally or within a community
- Spot rising content before it goes viral
- Analyze whether a topic is gaining or losing momentum over time
No API key. No OAuth. Just Reddit's public JSON endpoints.
Create a config.yaml:
server:
name: "reddit-mcp"
version: "0.1.0"
transport:
type: "stdio"
reddit:
user_agent: "MCP-TrendBot/1.0 (by /u/yourusername)"
⚠️ Always set a properuser_agent. Reddit blocks requests with missing or generic user agents. Use your actual Reddit username.
server:
name: "reddit-mcp"
version: "0.1.0"
transport:
type: "http"
http:
host: ":8080"
reddit:
user_agent: "MCP-TrendBot/1.0 (by /u/yourusername)"See docs/config-stdio.yaml and docs/config-http.yaml for full examples.
go mod tidy
make build
./bin/reddit-mcp -config config.yaml| Tool | What it does |
|---|---|
discover_communities |
Find subreddits for a single topic, sorted by subscribers |
get_crossover_communities |
Find subreddits covering multiple topics at once, ranked by overlap |
get_subreddit_info |
Stats about a subreddit: subscribers, active users, description |
| Tool | What it does |
|---|---|
get_trending_posts |
Posts from known subreddits, merged and sorted by trend score |
get_topic_trends |
Global Reddit search across multiple topics at once |
get_subreddit_pulse |
Current state of a single community (hot/new/top/rising) |
search_posts |
Search posts by keyword, globally or within a subreddit |
get_rising_posts |
Posts gaining momentum in r/all right now |
| Tool | What it does |
|---|---|
analyze_sentiment_trend |
Compare topic momentum: last 24h vs last N days |
All tools that return posts accept a jq_filter parameter. Always use it to avoid burning context.
Every post comes with a trend_score calculated as:
trend_score = velocity × (1 + engagement)
velocity = score / age_hours
engagement = num_comments / max(score, 1)
A post with 500 upvotes from 2 hours ago scores much higher than one with 2000 upvotes from 3 days ago. This gives a real signal of what's actually hot right now, not just what accumulated votes over time.
All tools that return posts accept a jq_filter parameter. This is the key to keeping output compact and avoiding context blowup.
Always provide one. The tool descriptions include recommended filters.
# Compact list — title, score and link only
[.[] | {title, score, permalink}]
# Top 5 posts sorted by trend score
sort_by(-.trend_score) | .[0:5]
# Only high-scoring posts
[.[] | select(.score > 500)]
# For get_topic_trends — 3 posts per topic, minimal fields
[.[] | {topic, posts: [.posts[:3] | .[] | {title, score, trend_score, subreddit}]}]If the filter is invalid, the tool falls back to full unfiltered output.
When exploring multiple topics (e.g. kubernetes, cloud, golang, AI):
Step 1 — Find the right communities:
get_crossover_communities(
topics: ["kubernetes", "cloud", "golang", "AI"],
limit_per_topic: 5
)
This gives you subreddits ranked by how many of your topics they cover.
Step 2 — Get trending posts from those communities:
get_trending_posts(
subreddits: ["devops", "kubernetes", "golang", "MachineLearning"],
time_range: "week",
limit: 5,
jq_filter: "[.[:20] | .[] | {title, subreddit, score, trend_score, permalink}]"
)
Two calls. Compact output. High-quality results from actual communities.
docker build -t reddit-mcp .
docker run -v $(pwd)/config.yaml:/config/config.yaml reddit-mcpReddit allows ~60 requests/minute without authentication. If you're making many calls, add a small delay between them. The server doesn't implement automatic backoff — handle it at the application level if needed.
You've hit Reddit's rate limit. Wait a minute and try again.
The subreddit might be private, very small, or the query too specific. Use get_subreddit_info to validate a community before fetching posts from it.
Invalid jq syntax falls back to unfiltered output. Check the filter syntax if you're getting more data than expected.
Your user_agent is being blocked. Make sure it's set and follows the format AppName/Version (by /u/username).
For AI agents working on this codebase, see AGENTS.md.
Apache 2.0