Tutorial: Reddit - Gnist Context

Media

Data source: Reddit (reddit.com)

Overview

Reddit wraps Reddit (reddit.com), handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-reddit": {
      "url": "https://context.gnist.ai/mcp/reddit/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_reddit`

Search Reddit posts by keyword, optionally within a specific subreddit. Returns: Dictionary with 'count' and 'posts' list. Each post has id, title, author, subreddit, url, permalink, selftext, score, upvote_ratio, num_comments, created_utc, is_self, link_flair_text.

Parameter	Type	Required	Description
`query`	string	required	Search terms (e.g. "machine learning", "Python async"). Searches across post titles and body text.
`subreddit`	any	optional	Restrict search to a specific subreddit (e.g. "python", "MachineLearning"). Optional.
`sort`	string	optional	Sort order: relevance, hot, top, new, comments. Default: relevance. (default: `relevance`)
`time_filter`	string	optional	Time filter: hour, day, week, month, year, all. Default: all. (default: `all`)
`limit`	integer	optional	Number of results (1-25, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/reddit/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_reddit", "arguments": {"query": "machine learning"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/reddit/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'machine learning'},
            'name': 'search_reddit'}},
)
print(resp.json())

`get_subreddit_posts`

Get posts from a specific subreddit sorted by hot, new, top, or rising. Returns: Dictionary with 'count' and 'posts' list.

Parameter	Type	Required	Description
`subreddit`	string	required	Subreddit name without r/ prefix (e.g. "python", "worldnews", "AskReddit").
`sort`	string	optional	Sort: hot, new, top, rising, controversial. Default: hot. (default: `hot`)
`time_filter`	string	optional	Time filter for top/controversial: hour, day, week, month, year, all. (default: `day`)
`limit`	integer	optional	Number of posts (1-25, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/reddit/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_subreddit_posts", "arguments": {"subreddit": "python"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/reddit/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'subreddit': 'python'},
            'name': 'get_subreddit_posts'}},
)
print(resp.json())

`get_subreddit_info`

Get metadata about a subreddit — name, description, subscribers, active users, etc. Returns: Subreddit info: name, title, description, subscribers, active_users, created_utc, over18, url, subreddit_type.

Parameter	Type	Required	Description
`subreddit`	string	required	Subreddit name without r/ prefix (e.g. "python", "worldnews").

curl -X POST "https://context.gnist.ai/mcp/reddit/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_subreddit_info", "arguments": {"subreddit": "python"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/reddit/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'subreddit': 'python'}, 'name': 'get_subreddit_info'}},
)
print(resp.json())

`get_reddit_post_comments`

Get a Reddit post and its top-level comments by post ID. Returns: Dictionary with 'post' (full post data) and 'comments' list. Each comment has id, author, body, score, created_utc, depth.

Parameter	Type	Required	Description
`post_id`	string	required	Reddit post ID (the short alphanumeric ID, e.g. "1abc2d").
`sort`	string	optional	Sort: top, best, new, controversial, old, qa. Default: top. (default: `top`)
`limit`	integer	optional	Number of comments (1-50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/reddit/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_reddit_post_comments", "arguments": {"post_id": "1abc2d"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/reddit/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'post_id': '1abc2d'},
            'name': 'get_reddit_post_comments'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/reddit/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/reddit/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_reddit to find items, then get_subreddit_posts to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Reddit provide?

Search Reddit posts, browse subreddits, and read comments. Find discussions, opinions, and community insights on any topic. It exposes 5 tools: search_reddit, get_subreddit_posts, get_subreddit_info, get_reddit_post_comments, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Reddit API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.