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)
