Content
# Reddit MCP Server
[](https://pypi.org/project/reddit-no-auth-mcp-server/)
[](https://github.com/eliasbiondo/reddit-mcp-server/blob/main/LICENSE)
A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that
provides AI assistants with access to Reddit data. Built on top of
[redd](https://github.com/eliasbiondo/redd) — no API keys required.
https://github.com/user-attachments/assets/af8ae52c-f9f3-4d04-80d5-4be0dfa61b0f
---
## Table of Contents
1. [Features](#1-features)
2. [Quick Start](#2-quick-start)
3. [Available Tools](#3-available-tools)
4. [Configuration](#4-configuration)
5. [Architecture](#5-architecture)
6. [Contributing](#6-contributing)
7. [License](#7-license)
---
## 1. Features
- 🔍 **Search** — Search all of Reddit or within a specific subreddit
- 📰 **Subreddit Posts** — Browse hot, top, new, or rising posts from any subreddit
- 📖 **Post Details** — Get full post content with nested comment trees
- 👤 **User Activity** — View a user's recent posts and comments
- 📝 **User Posts** — Get a user's submitted posts
No API keys, no authentication, no browser required. Just install and run.
---
## 2. Quick Start
### 2.1. Using `uvx` (recommended)
The fastest way to run the server — no clone needed:
```bash
# stdio transport (default, for Claude Desktop / Cursor / etc.)
uvx reddit-no-auth-mcp-server
# HTTP transport
uvx reddit-no-auth-mcp-server \
--transport streamable-http \
--port 8000
```
### 2.2. From source
```bash
git clone https://github.com/eliasbiondo/reddit-mcp-server.git
cd reddit-mcp-server
uv sync
```
Run the server:
```bash
# stdio transport (default)
uv run reddit-no-auth-mcp-server
# HTTP transport
uv run reddit-no-auth-mcp-server \
--transport streamable-http \
--port 8000
```
### 2.3. MCP Client Configuration
#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"reddit": {
"command": "uvx",
"args": ["reddit-no-auth-mcp-server"]
}
}
}
```
#### Cursor
Add to your `.cursor/mcp.json`:
```json
{
"mcpServers": {
"reddit": {
"command": "uvx",
"args": ["reddit-no-auth-mcp-server"]
}
}
}
```
#### From source (any MCP client)
```json
{
"mcpServers": {
"reddit": {
"command": "uv",
"args": [
"--directory", "/path/to/reddit-mcp-server",
"run", "reddit-no-auth-mcp-server"
]
}
}
}
```
---
## 3. Available Tools
| Tool | Description | Key Arguments |
|------|-------------|---------------|
| `search` | Search Reddit for posts | `query`, `limit`, `sort` |
| `search_subreddit` | Search within a subreddit | `subreddit`, `query`, `limit`, `sort` |
| `get_post` | Get post details + comment tree | `permalink` |
| `get_subreddit_posts` | Get subreddit listing | `subreddit`, `limit`, `category`, `time_filter` |
| `get_user` | Get user's activity feed | `username`, `limit` |
| `get_user_posts` | Get user's submitted posts | `username`, `limit`, `category`, `time_filter` |
### Tool Details
#### `search`
Search all of Reddit for posts matching a query.
```
query: "python async programming"
limit: 10
sort: "relevance" # relevance, hot, top, new, comments
```
#### `search_subreddit`
Search within a specific subreddit.
```
subreddit: "Python"
query: "web scraping"
limit: 10
sort: "top"
```
#### `get_post`
Get full details of a Reddit post including its comment tree.
```
permalink: "/r/Python/comments/abc123/my_post/"
```
#### `get_subreddit_posts`
Get posts from a subreddit listing.
```
subreddit: "MachineLearning"
limit: 25
category: "hot" # hot, top, new, rising
time_filter: "week" # hour, day, week, month, year, all
```
#### `get_user`
Get a user's recent public activity (posts and comments).
```
username: "spez"
limit: 10
```
#### `get_user_posts`
Get a user's submitted posts.
```
username: "spez"
limit: 10
category: "top" # hot, top, new
time_filter: "all" # hour, day, week, month, year, all
```
---
## 4. Configuration
All settings can be configured via environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `REDDIT_TRANSPORT` | `stdio` | MCP transport (`stdio`, `streamable-http`) |
| `REDDIT_HOST` | `127.0.0.1` | Host for HTTP transport |
| `REDDIT_PORT` | `8000` | Port for HTTP transport |
| `REDDIT_PATH` | `/mcp` | Path for HTTP transport |
| `REDDIT_LOG_LEVEL` | `WARNING` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `REDDIT_PROXY` | — | HTTP/HTTPS proxy URL |
| `REDDIT_TIMEOUT` | `10.0` | Request timeout in seconds |
| `REDDIT_THROTTLE_MIN` | `1.0` | Min delay between paginated requests (seconds) |
| `REDDIT_THROTTLE_MAX` | `2.0` | Max delay between paginated requests (seconds) |
CLI arguments take precedence over environment variables:
```bash
uv run reddit-no-auth-mcp-server \
--transport streamable-http \
--port 9000 \
--log-level DEBUG
```
---
## 5. Architecture
This project follows **hexagonal architecture** (ports & adapters):
```
src/reddit_mcp_server/
├── domain/ # Pure business logic, no framework imports
│ ├── exceptions.py # Domain exception hierarchy
│ └── value_objects.py # Immutable config objects
├── ports/ # Abstract interfaces (contracts)
│ ├── config.py # ConfigPort
│ └── reddit.py # RedditPort
├── application/ # Use cases (orchestration)
│ ├── search.py
│ ├── search_subreddit.py
│ ├── get_post.py
│ ├── get_user.py
│ ├── get_subreddit_posts.py
│ └── get_user_posts.py
├── adapters/
│ ├── inbound/ # Presentation layer
│ │ ├── cli.py # CLI entry point
│ │ ├── mcp_server.py
│ │ ├── error_mapping.py
│ │ ├── serialization.py
│ │ └── mcp_tools/ # MCP tool definitions
│ └── outbound/ # Infrastructure layer
│ ├── env_config.py # ConfigPort implementation
│ └── redd_client.py # RedditPort implementation (wraps redd)
└── container.py # DI composition root
```
---
## 6. Contributing
Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
guidelines on setting up the project, running tests, and submitting changes.
---
## 7. License
[MIT](LICENSE)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
context7-mcp
Context7 MCP Server provides natural language access to documentation for...
langchain_data_agent
NL2SQL - Ask questions in plain English, get SQL queries and results....
gram
Platform to create, curate and host MCP servers ⚒️ Build production quality...
yt-dlp-mcp
A powerful MCP server for integrating video capabilities into AI agents.