# Reddit MCP Tool
A Model Context Protocol (MCP) server that provides read-only tools for browsing and searching Reddit content through Reddit's official API. This server allows you to search for posts, read post details, and get subreddit information through MCP-compatible clients.
## Features
- 🔍 **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
## Prerequisites
1. **Python 3.10+** installed on your system
2. **uv** package manager installed ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
3. **Reddit API credentials** (see setup section below)
## Reddit API Setup
1. **Create a Reddit App**:
- Go to [Reddit App Preferences](https://old.reddit.com/prefs/apps/)
- 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)
2. **Get Your Credentials**:
- **Client ID**: Found under your app name (short string)
- **Client Secret**: Found in the app details (longer string)
## Installation
1. **Clone or download this repository**:
```bash
git clone <repository-url>
cd reddit-mcp-tool
```
2. **Install dependencies using uv**:
```bash
uv sync
```
3. **Set up environment variables**:
```bash
cp env.example .env
```
Edit the `.env` file with your Reddit API credentials:
```env
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here
REDDIT_USER_AGENT=reddit-mcp-tool:v0.1.7 (by /u/yourusername)
```
**Note**: This server operates in read-only mode and only requires the client ID, secret, and user agent for basic API access.
## Usage
### Running the MCP Server
```bash
uv run reddit-mcp-tool
```
Or directly with Python:
```bash
uv run python -m reddit_mcp.server
```
### Available Tools
#### 1. Search Reddit Posts (Subreddit-specific)
Search for posts in a specific subreddit:
```json
{
"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")
#### 2. Search All Reddit (Site-wide)
Search across all of Reddit:
```json
{
"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")
#### 3. Get Post Details
Get detailed information about a specific post:
```json
{
"name": "get_reddit_post_details",
"arguments": {
"post_id": "abc123"
}
}
```
**Parameters:**
- `post_id` (required): The Reddit post ID
#### 4. Get Subreddit Information
Get information about a subreddit:
```json
{
"name": "get_subreddit_info",
"arguments": {
"subreddit": "python"
}
}
```
**Parameters:**
- `subreddit` (required): The subreddit name (without r/)
#### 5. Get Hot Posts
Get hot posts from a subreddit:
```json
{
"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)
### Search Tool Comparison
| Feature | `search_reddit_posts` | `search_reddit_all` |
| ------------ | ------------------------- | -------------------------- |
| **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 |
## Configuration
### Environment Variables
| Variable | Required | Description |
| ---------------------- | -------- | ---------------------------------- |
| `REDDIT_CLIENT_ID` | Yes | Your Reddit app's client ID |
| `REDDIT_CLIENT_SECRET` | Yes | Your Reddit app's client secret |
| `REDDIT_USER_AGENT` | Yes | User agent string for API requests |
## Integration with MCP Clients
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.
### Claude Desktop Configuration
Add this to your Claude Desktop configuration:
```json
{
"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.1.7 (by /u/yourusername)"
}
}
}
}
```
### Local Development Configuration
For local development, use:
```json
{
"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.1.7 (by /u/yourusername)"
}
}
}
}
```
## Error Handling
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.
## Rate Limiting
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.
## Development
### Running Tests
```bash
uv run pytest
```
### Code Formatting
```bash
uv run black .
uv run ruff check .
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Submit a pull request
## License
This project is licensed under the MIT License. See LICENSE file for details.
## Disclaimer
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.
## Notes
- 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
Raw data
{
"_id": null,
"home_page": null,
"name": "reddit-mcp-tool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, mcp, model-context-protocol, reddit, search",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/18/ee/8cfbe40634672d37aa91394389dad31ce85219592b0dff295e2f30030766/reddit_mcp_tool-0.1.9.tar.gz",
"platform": null,
"description": "# Reddit MCP Tool\n\nA Model Context Protocol (MCP) server that provides read-only tools for browsing and searching Reddit content through Reddit's official API. This server allows you to search for posts, read post details, and get subreddit information through MCP-compatible clients.\n\n## Features\n\n- \ud83d\udd0d **Search Posts**: Search for posts in specific subreddits with various sorting and filtering options\n- \ud83c\udf10 **Site-wide Search**: Search across all of Reddit with keyword queries\n- \ud83d\udcca **Get Subreddit Info**: Retrieve detailed information about subreddits\n- \ud83d\udd25 **Get Hot Posts**: Fetch hot posts from subreddits\n- \ud83d\udccb **Get Post Details**: Get comprehensive details about specific posts\n\n## Prerequisites\n\n1. **Python 3.10+** installed on your system\n2. **uv** package manager installed ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))\n3. **Reddit API credentials** (see setup section below)\n\n## Reddit API Setup\n\n1. **Create a Reddit App**:\n\n - Go to [Reddit App Preferences](https://old.reddit.com/prefs/apps/)\n - Click \"Create App\" or \"Create Another App\"\n - Choose \"script\" for the app type\n - Fill in the required fields:\n - Name: Your app name (e.g., \"Reddit MCP Tool\")\n - Description: Brief description\n - About URL: Can be blank\n - Redirect URI: http://localhost:8080 (required but not used)\n\n2. **Get Your Credentials**:\n - **Client ID**: Found under your app name (short string)\n - **Client Secret**: Found in the app details (longer string)\n\n## Installation\n\n1. **Clone or download this repository**:\n\n ```bash\n git clone <repository-url>\n cd reddit-mcp-tool\n ```\n\n2. **Install dependencies using uv**:\n\n ```bash\n uv sync\n ```\n\n3. **Set up environment variables**:\n\n ```bash\n cp env.example .env\n ```\n\n Edit the `.env` file with your Reddit API credentials:\n\n ```env\n REDDIT_CLIENT_ID=your_client_id_here\n REDDIT_CLIENT_SECRET=your_client_secret_here\n REDDIT_USER_AGENT=reddit-mcp-tool:v0.1.7 (by /u/yourusername)\n ```\n\n **Note**: This server operates in read-only mode and only requires the client ID, secret, and user agent for basic API access.\n\n## Usage\n\n### Running the MCP Server\n\n```bash\nuv run reddit-mcp-tool\n```\n\nOr directly with Python:\n\n```bash\nuv run python -m reddit_mcp.server\n```\n\n### Available Tools\n\n#### 1. Search Reddit Posts (Subreddit-specific)\n\nSearch for posts in a specific subreddit:\n\n```json\n{\n \"name\": \"search_reddit_posts\",\n \"arguments\": {\n \"subreddit\": \"python\",\n \"query\": \"machine learning\",\n \"limit\": 10,\n \"sort\": \"relevance\",\n \"time_filter\": \"week\"\n }\n}\n```\n\n**Parameters:**\n\n- `subreddit` (required): The subreddit name (without r/)\n- `query` (required): Search query string\n- `limit` (optional): Number of posts to return (1-100, default: 10)\n- `sort` (optional): Sort method - \"relevance\", \"hot\", \"top\", \"new\", \"comments\" (default: \"relevance\")\n- `time_filter` (optional): Time filter - \"all\", \"day\", \"week\", \"month\", \"year\" (default: \"all\")\n\n#### 2. Search All Reddit (Site-wide)\n\nSearch across all of Reddit:\n\n```json\n{\n \"name\": \"search_reddit_all\",\n \"arguments\": {\n \"query\": \"artificial intelligence\",\n \"limit\": 20,\n \"sort\": \"top\",\n \"time_filter\": \"week\"\n }\n}\n```\n\n**Parameters:**\n\n- `query` (required): Search query string\n- `limit` (optional): Number of posts to return (1-100, default: 10)\n- `sort` (optional): Sort method - \"relevance\", \"hot\", \"top\", \"new\", \"comments\" (default: \"relevance\")\n- `time_filter` (optional): Time filter - \"all\", \"day\", \"week\", \"month\", \"year\" (default: \"all\")\n\n#### 3. Get Post Details\n\nGet detailed information about a specific post:\n\n```json\n{\n \"name\": \"get_reddit_post_details\",\n \"arguments\": {\n \"post_id\": \"abc123\"\n }\n}\n```\n\n**Parameters:**\n\n- `post_id` (required): The Reddit post ID\n\n#### 4. Get Subreddit Information\n\nGet information about a subreddit:\n\n```json\n{\n \"name\": \"get_subreddit_info\",\n \"arguments\": {\n \"subreddit\": \"python\"\n }\n}\n```\n\n**Parameters:**\n\n- `subreddit` (required): The subreddit name (without r/)\n\n#### 5. Get Hot Posts\n\nGet hot posts from a subreddit:\n\n```json\n{\n \"name\": \"get_hot_reddit_posts\",\n \"arguments\": {\n \"subreddit\": \"programming\",\n \"limit\": 15\n }\n}\n```\n\n**Parameters:**\n\n- `subreddit` (required): The subreddit name (without r/)\n- `limit` (optional): Number of posts to return (1-100, default: 10)\n\n### Search Tool Comparison\n\n| Feature | `search_reddit_posts` | `search_reddit_all` |\n| ------------ | ------------------------- | -------------------------- |\n| **Scope** | Single subreddit | All Reddit |\n| **Use Case** | Focused community search | Broad topic discovery |\n| **Results** | From one subreddit | From multiple subreddits |\n| **Example** | \"python\" in r/programming | \"python\" across all Reddit |\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n| ---------------------- | -------- | ---------------------------------- |\n| `REDDIT_CLIENT_ID` | Yes | Your Reddit app's client ID |\n| `REDDIT_CLIENT_SECRET` | Yes | Your Reddit app's client secret |\n| `REDDIT_USER_AGENT` | Yes | User agent string for API requests |\n\n## Integration with MCP Clients\n\nThis 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.\n\n### Claude Desktop Configuration\n\nAdd this to your Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"reddit-mcp-tool\": {\n \"command\": \"uvx\",\n \"args\": [\"reddit-mcp-tool@latest\"],\n \"env\": {\n \"REDDIT_CLIENT_ID\": \"your_client_id_here\",\n \"REDDIT_CLIENT_SECRET\": \"your_client_secret_here\",\n \"REDDIT_USER_AGENT\": \"reddit-mcp-tool:v0.1.7 (by /u/yourusername)\"\n }\n }\n }\n}\n```\n\n### Local Development Configuration\n\nFor local development, use:\n\n```json\n{\n \"mcpServers\": {\n \"reddit-mcp-tool\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"reddit-mcp-tool\"],\n \"cwd\": \"/path/to/reddit-mcp-tool\",\n \"env\": {\n \"REDDIT_CLIENT_ID\": \"your_client_id_here\",\n \"REDDIT_CLIENT_SECRET\": \"your_client_secret_here\",\n \"REDDIT_USER_AGENT\": \"reddit-mcp-tool:v0.1.7 (by /u/yourusername)\"\n }\n }\n }\n}\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling for common scenarios:\n\n- Invalid subreddit names\n- Post not found\n- Authentication failures\n- Rate limiting\n- Network errors\n\nAll errors are returned as descriptive text content through the MCP protocol.\n\n## Rate Limiting\n\nReddit'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.\n\n## Development\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Code Formatting\n\n```bash\nuv run black .\nuv run ruff check .\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License. See LICENSE file for details.\n\n## Disclaimer\n\nThis 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.\n\n## Notes\n\n- This project was renamed to `reddit-mcp-tool` to avoid conflicts with the existing `reddit-mcp` package on PyPI\n- Only read-only operations are supported (search, read posts, get subreddit info)\n- No user authentication is required - only app credentials for basic API access\n- Built with the reliable PRAW (Python Reddit API Wrapper) library\n- Includes proper rate limiting and error handling\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Reddit MCP server for reading and searching Reddit content",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"api",
" mcp",
" model-context-protocol",
" reddit",
" search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "015f356edd54c010281c264d8269097464b6b7f7d4b509d42f8de21bfeaaf077",
"md5": "546283a81e894c6dee87d9b4ed335bd9",
"sha256": "1fe8db520bcd9ecf15f6d63c1f35965803c04568fa283e2eff8a47040d4f9391"
},
"downloads": -1,
"filename": "reddit_mcp_tool-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "546283a81e894c6dee87d9b4ed335bd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8700,
"upload_time": "2025-08-26T07:51:07",
"upload_time_iso_8601": "2025-08-26T07:51:07.291626Z",
"url": "https://files.pythonhosted.org/packages/01/5f/356edd54c010281c264d8269097464b6b7f7d4b509d42f8de21bfeaaf077/reddit_mcp_tool-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "18ee8cfbe40634672d37aa91394389dad31ce85219592b0dff295e2f30030766",
"md5": "8a04453008f6813f55f53eb2fb9a34a3",
"sha256": "90552c4975cdd7d77da6bcf56ac7dd23f7c06434ec43bfe68d6f694ff480ae1e"
},
"downloads": -1,
"filename": "reddit_mcp_tool-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "8a04453008f6813f55f53eb2fb9a34a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 94309,
"upload_time": "2025-08-26T07:51:08",
"upload_time_iso_8601": "2025-08-26T07:51:08.260434Z",
"url": "https://files.pythonhosted.org/packages/18/ee/8cfbe40634672d37aa91394389dad31ce85219592b0dff295e2f30030766/reddit_mcp_tool-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 07:51:08",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "reddit-mcp-tool"
}
JSON