Metadata-Version: 2.4
Name: reddit-no-auth-mcp-server
Version: 0.1.0
Summary: A Model Context Protocol Server for Reddit — browse, search, and read Reddit from any MCP client. No API keys required.
Project-URL: Homepage, https://github.com/eliasbiondo/reddit-mcp-server
Project-URL: Repository, https://github.com/eliasbiondo/reddit-mcp-server
Project-URL: Issues, https://github.com/eliasbiondo/reddit-mcp-server/issues
Author-email: Elias Biondo <contato@eliasbiondo.com>
License: MIT
License-File: LICENSE
Keywords: ai,llm,mcp,model-context-protocol,redd,reddit,scraper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: redd>=0.2.0
Description-Content-Type: text/markdown

# Reddit MCP Server

[![PyPI](https://img.shields.io/pypi/v/reddit-no-auth-mcp-server?label=pypi&cacheSeconds=3600)](https://pypi.org/project/reddit-no-auth-mcp-server/)
[![License: MIT](https://img.shields.io/github/license/eliasbiondo/reddit-mcp-server?cacheSeconds=3600)](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.

## 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.

## Quick Start

### Install & Run

The fastest way to run the server is with [`uvx`](https://docs.astral.sh/uv/):

```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
```

<details>
<summary><strong>From source</strong></summary>

```bash
git clone https://github.com/eliasbiondo/reddit-mcp-server.git
cd reddit-mcp-server
uv sync
reddit-mcp-server
```

</details>

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": ["reddit-no-auth-mcp-server"]
    }
  }
}
```

### Configure with Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": ["reddit-no-auth-mcp-server"]
    }
  }
}
```

## 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
```

## 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
reddit-mcp-server --transport streamable-http --port 9000 --log-level DEBUG
```

## 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
```

## License

[MIT](LICENSE)
