Reddit MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to Reddit data. Built on top of redd — no API keys required.

https://github.com/user-attachments/assets/af8ae52c-f9f3-4d04-80d5-4be0dfa61b0f

Features
Quick Start
Available Tools
Configuration
Architecture
Contributing
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:

hljs language-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

hljs language-bash

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

Run the server:

hljs language-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:

hljs language-json

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

Cursor

Add to your .cursor/mcp.json:

hljs language-json

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

From source (any MCP client)

hljs language-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.

hljs language-vbnet

query: "python async programming"
limit: 10
sort: "relevance"  # relevance, hot, top, new, comments

`search_subreddit`

Search within a specific subreddit.

hljs language-vbnet

subreddit: "Python"
query: "web scraping"
limit: 10
sort: "top"

`get_post`

Get full details of a Reddit post including its comment tree.

hljs language-vbnet

permalink: "/r/Python/comments/abc123/my_post/"

`get_subreddit_posts`

Get posts from a subreddit listing.

hljs language-sql

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

hljs language-vbnet

username: "spez"
limit: 10

`get_user_posts`

Get a user's submitted posts.

hljs language-sql

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:

hljs language-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):

hljs language-bash

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 for guidelines on setting up the project, running tests, and submitting changes.

7. License

MIT

reddit-mcp-server

Reddit MCP Server

Table of Contents

1. Features

2. Quick Start

2.1. Using `uvx` (recommended)

2.2. From source

2.3. MCP Client Configuration

Claude Desktop

Cursor

From source (any MCP client)

3. Available Tools

Tool Details

`search`

`search_subreddit`

`get_post`

`get_subreddit_posts`

`get_user`

`get_user_posts`

4. Configuration

5. Architecture

6. Contributing

7. License

Similar Packages

Original Author

Publisher

reddit-mcp-server

Reddit MCP Server

Table of Contents

1. Features

2. Quick Start

2.1. Using uvx (recommended)

2.2. From source

2.3. MCP Client Configuration

Claude Desktop

Cursor

From source (any MCP client)

3. Available Tools

Tool Details

search

search_subreddit

get_post

get_subreddit_posts

get_user

get_user_posts

4. Configuration

5. Architecture

6. Contributing

7. License

Similar Packages

Original Author

Publisher

2.1. Using `uvx` (recommended)

`search`

`search_subreddit`

`get_post`

`get_subreddit_posts`

`get_user`

`get_user_posts`