Provides read-only access to Reddit's API for browsing and searching content, including searching posts in subreddits, retrieving post details, getting subreddit information, and fetching hot posts with various sorting and filtering options.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Reddit MCP Tool search for posts about Python tutorials in r/learnprogramming"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides read-only tools for browsing and searching Reddit content through Reddit's official API. Built with FastMCP for seamless integration and automatic serialization. This server allows you to search for posts, read post details, and get subreddit information through MCP-compatible clients.
🔍 Search Posts: Search for posts in specific subreddits with various sorting and filtering options
🌐 Site-wide Search: Search across all of Reddit with keyword queries
📊 Get Subreddit Info: Retrieve detailed information about subreddits
🔥 Get Hot Posts: Fetch hot posts from subreddits
📋 Get Post Details: Get comprehensive details about specific posts
⚡ FastMCP Integration: Built with FastMCP for automatic serialization and seamless MCP compatibility
Related MCP server: Reddit MCP Server
Python 3.10+ installed on your system
uv package manager installed (installation guide)
Reddit API credentials (see setup section below)
Create a Reddit App:
Go to Reddit App Preferences
Click "Create App" or "Create Another App"
Choose "script" for the app type
Fill in the required fields:
Name: Your app name (e.g., "Reddit MCP Tool")
Description: Brief description
About URL: Can be blank
Redirect URI: http://localhost:8080 (required but not used)
Get Your Credentials:
Client ID: Found under your app name (short string)
Client Secret: Found in the app details (longer string)
Clone or download this repository:
git clone <repository-url>
cd reddit-mcp-toolInstall dependencies using uv:
uv syncQuick setup (recommended):
uv run python scripts/setup.pyThis will create your .env file and show you what to do next.
Manual setup:
cp env.example .envEdit the .env file with your Reddit API credentials:
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here
REDDIT_USER_AGENT=reddit-mcp-tool:v0.2.0 (by /u/yourusername)Test your setup:
uv run python scripts/test_basic.pyNote: This server operates in read-only mode and only requires the client ID, secret, and user agent for basic API access.
If you encounter issues, see TROUBLESHOOTING.md for detailed solutions to common problems.
uv run reddit-mcp-toolOr directly with Python:
uv run python -m reddit_mcp.serverSearch for posts in a specific subreddit:
{
"name": "search_reddit_posts",
"arguments": {
"subreddit": "python",
"query": "machine learning",
"limit": 10,
"sort": "relevance",
"time_filter": "week"
}
}Parameters:
subreddit (required): The subreddit name (without r/)
query (required): Search query string
limit (optional): Number of posts to return (1-100, default: 10)
sort (optional): Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance")
time_filter (optional): Time filter - "all", "day", "week", "month", "year" (default: "all")
Search across all of Reddit:
{
"name": "search_reddit_all",
"arguments": {
"query": "artificial intelligence",
"limit": 20,
"sort": "top",
"time_filter": "week"
}
}Parameters:
query (required): Search query string
limit (optional): Number of posts to return (1-100, default: 10)
sort (optional): Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance")
time_filter (optional): Time filter - "all", "day", "week", "month", "year" (default: "all")
Get detailed information about a specific post:
{
"name": "get_reddit_post_details",
"arguments": {
"post_id": "abc123"
}
}Parameters:
post_id (required): The Reddit post ID
Get information about a subreddit:
{
"name": "get_subreddit_info",
"arguments": {
"subreddit": "python"
}
}Parameters:
subreddit (required): The subreddit name (without r/)
Get hot posts from a subreddit:
{
"name": "get_hot_reddit_posts",
"arguments": {
"subreddit": "programming",
"limit": 15
}
}Parameters:
subreddit (required): The subreddit name (without r/)
limit (optional): Number of posts to return (1-100, default: 10)
Feature |
|
|
Scope | Single subreddit | All Reddit |
Use Case | Focused community search | Broad topic discovery |
Results | From one subreddit | From multiple subreddits |
Example | "python" in r/programming | "python" across all Reddit |
Variable | Required | Description |
| Yes | Your Reddit app's client ID |
| Yes | Your Reddit app's client secret |
| Yes | User agent string for API requests |
This server implements the Model Context Protocol and can be used with any MCP-compatible client. Configure your MCP client to connect to this server using stdio transport.
Add this to your Claude Desktop configuration:
{
"mcpServers": {
"reddit-mcp-tool": {
"command": "uvx",
"args": ["reddit-mcp-tool@latest"],
"env": {
"REDDIT_CLIENT_ID": "your_client_id_here",
"REDDIT_CLIENT_SECRET": "your_client_secret_here",
"REDDIT_USER_AGENT": "reddit-mcp-tool:v0.2.0 (by /u/yourusername)"
}
}
}
}For local development, use:
{
"mcpServers": {
"reddit-mcp-tool": {
"command": "uv",
"args": ["run", "reddit-mcp-tool"],
"cwd": "/path/to/reddit-mcp-tool",
"env": {
"REDDIT_CLIENT_ID": "your_client_id_here",
"REDDIT_CLIENT_SECRET": "your_client_secret_here",
"REDDIT_USER_AGENT": "reddit-mcp-tool:v0.2.0 (by /u/yourusername)"
}
}
}
}The server includes comprehensive error handling for common scenarios:
Invalid subreddit names
Post not found
Authentication failures
Rate limiting
Network errors
All errors are returned as descriptive text content through the MCP protocol.
Reddit's API has rate limits. The server respects these limits, but you may encounter rate limiting errors if you make too many requests in a short period. The default rate limit for authenticated users is typically 60 requests per minute.
uv run pytestuv run black .
uv run ruff check .Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run the test suite
Submit a pull request
This project is licensed under the MIT License. See LICENSE file for details.
This tool is for educational and development purposes. Please ensure you comply with Reddit's API Terms of Service and community guidelines when using this tool. This is a read-only tool that respects Reddit's API limits and does not provide any posting or commenting capabilities.
This project was renamed to reddit-mcp-tool to avoid conflicts with the existing reddit-mcp package on PyPI
Only read-only operations are supported (search, read posts, get subreddit info)
No user authentication is required - only app credentials for basic API access
Built with the reliable PRAW (Python Reddit API Wrapper) library
Includes proper rate limiting and error handling
Get hot posts from a subreddit
Args: subreddit: The name of the subreddit (without r/) limit: Number of posts to return (default: 10, max: 100)
Returns: Human readable string containing hot posts
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| subreddit | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return format ('Human readable string') but lacks critical details: whether authentication is required, rate limits, error handling, or what 'hot' means algorithmically. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence adds value: the first states the action, and the subsequent lines provide essential parameter and output details without redundancy. It's front-loaded and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (implied by 'Has output schema: true'), the description doesn't need to detail return values. However, with no annotations and 2 parameters, it partially compensates with parameter semantics but lacks behavioral context like authentication or rate limits. For a simple read operation, it's adequate but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'subreddit' excludes the 'r/' prefix and provides default and max values for 'limit', which aren't in the schema. This compensates well for the low schema coverage, though it doesn't detail parameter constraints like valid subreddit formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'hot posts from a subreddit', making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_subreddit_info' or 'search_reddit_posts', which might also retrieve subreddit content. The purpose is specific but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_reddit_posts' or 'get_subreddit_info'. It mentions what the tool does but offers no context about when it's appropriate, such as for trending content versus general searches, or prerequisites like authentication needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific Reddit post
Args: post_id: The Reddit post ID
Returns: Human readable string containing detailed post information
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions that it returns 'human readable string containing detailed post information', which gives some behavioral context about the output format. However, it lacks details on error handling, rate limits, authentication needs, or what 'detailed information' includes beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The 'Args' and 'Returns' sections are structured but could be more integrated. There's minimal waste, though the 'human readable string' note might be redundant if the output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter) and the presence of an output schema, the description is somewhat complete but has gaps. It covers the basic purpose and parameter, but without annotations, it should ideally include more behavioral context like error cases or usage distinctions from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It adds that 'post_id' is 'The Reddit post ID', which provides basic semantics beyond the schema's title 'Post Id'. However, it doesn't explain format (e.g., alphanumeric string), examples, or constraints, leaving gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed information about a specific Reddit post'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_hot_reddit_posts' or 'search_reddit_posts', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'search_reddit_posts' and 'get_hot_reddit_posts' available, there's no indication that this tool is for retrieving details of a known post ID rather than searching or listing posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a subreddit
Args: subreddit: The name of the subreddit (without r/)
Returns: Human readable string containing subreddit information
| Name | Required | Description | Default |
|---|---|---|---|
| subreddit | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It mentions the return format ('Human readable string') but doesn't disclose authentication needs, rate limits, error conditions, or whether it's a read-only operation. The description is functional but lacks important operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured with clear sections for Args and Returns. The main purpose is stated upfront, and the parameter documentation is concise. The structure helps with readability, though the 'Human readable string' return description could be more specific.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (though not shown), the description doesn't need to detail return values. However, with no annotations and minimal behavioral disclosure, the description is adequate but incomplete. It covers the basic purpose and parameter but lacks context about when to use it versus siblings and operational considerations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides clear parameter semantics: 'The name of the subreddit (without r/)'. This adds valuable context beyond the bare schema. However, with only one parameter, the baseline would be 4 if no param info was provided; the description adds some value but doesn't fully compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('information about a subreddit'). It distinguishes from siblings by focusing on subreddit metadata rather than posts or search, though it doesn't explicitly contrast with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_hot_reddit_posts or search_reddit_posts. The description only states what it does, not when it's appropriate or what distinguishes it from similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for posts across all of Reddit (site-wide search)
Args: query: The search query to search across all Reddit limit: Number of posts to return (default: 10, max: 100) sort: Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance") time_filter: Time filter - "all", "day", "week", "month", "year" (default: "all")
Returns: Human readable string containing search results from across Reddit
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| sort | No | relevance | |
| time_filter | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return format ('Human readable string containing search results') but doesn't cover important aspects like rate limits, authentication requirements, error conditions, or whether this is a read-only operation. The description is minimal beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently organized. It starts with the core purpose, then provides a clear Args section with bullet-point style documentation for each parameter, followed by a Returns section. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters with no schema descriptions and an output schema exists, the description does a good job documenting parameters but is light on behavioral context. For a search tool with sibling alternatives, more guidance on usage context would be beneficial. The existence of an output schema means the description doesn't need to detail return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter documentation with clear explanations for all 4 parameters, including defaults, ranges, and allowed values. With 0% schema description coverage, the description fully compensates by adding comprehensive semantic information beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for posts across all of Reddit (site-wide search)'. This specifies the verb (search), resource (posts), and scope (all of Reddit). However, it doesn't explicitly differentiate from sibling tools like 'search_reddit_posts', which might have different scope or functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'search_reddit_posts' and 'get_hot_reddit_posts', there's no indication of when this site-wide search is preferred over other search or listing methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for posts in a specific subreddit
Args: subreddit: The name of the subreddit to search in (without r/) query: The search query limit: Number of posts to return (default: 10, max: 100) sort: Sort method - "relevance", "hot", "top", "new", "comments" (default: "relevance") time_filter: Time filter - "all", "day", "week", "month", "year" (default: "all")
Returns: Human readable string containing search results
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| sort | No | relevance | |
| subreddit | Yes | ||
| time_filter | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions default values and limits, which is helpful, but doesn't cover important aspects like rate limits, authentication requirements, error conditions, or pagination behavior. For a search tool with no annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently organized. It starts with a clear purpose statement, then provides a parameter table with essential details, and ends with return information. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, no annotations, but has output schema), the description is fairly complete. It documents all parameters thoroughly and mentions the return format. The output schema existence means it doesn't need to detail return values. The main gap is lack of behavioral context like rate limits or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter documentation with clear explanations of each parameter's purpose, default values, and constraints. With 0% schema description coverage, this fully compensates by adding meaning beyond what the bare schema provides. The only minor gap is not explicitly stating that 'subreddit' should be provided without the 'r/' prefix.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for posts in a specific subreddit' - a specific verb ('search') and resource ('posts in a specific subreddit'). It doesn't explicitly distinguish from sibling tools like 'search_reddit_all' (which searches all of Reddit vs. a specific subreddit), but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'search_reddit_all' (for searching across Reddit) or 'get_hot_reddit_posts' (for getting hot posts without a query). The description only states what the tool does, not when it's appropriate relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: get_hot_reddit_posts retrieves trending posts from a subreddit, get_reddit_post_details fetches details for a specific post, get_subreddit_info provides subreddit metadata, search_reddit_all performs site-wide searches, and search_reddit_posts searches within a specific subreddit. There is no overlap or ambiguity between these functions.
All tool names follow a consistent verb_noun pattern with 'get_' or 'search_' prefixes, using snake_case throughout. The naming is predictable and clearly indicates the action and target resource, such as get_hot_reddit_posts and search_reddit_posts.
With 5 tools, the server is well-scoped for its purpose of accessing Reddit content. Each tool serves a distinct and necessary function for browsing, searching, and retrieving information, making the count appropriate without being too sparse or overwhelming.
The tool set covers core read-only operations for Reddit, including fetching posts, details, subreddit info, and searches. Minor gaps exist, such as the inability to interact with posts (e.g., upvoting, commenting) or access user-specific data, but agents can still perform essential browsing and search tasks effectively.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/rising…
Reddit: Reddit Data API offers streamlined access to Reddit’s public data, like posts, comments.
Reddit posts, comments, subreddits, and search for AI agents. Free key, self-minted, no signup.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/GeLi2001/reddit-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server