Skip to content
Back to search

reddit-mcp-server

πŸ”— A zero-config Model Context Protocol (MCP) server for Reddit β€” search posts, browse subreddits, scrape user activity, and get structured data via any MCP-compatible AI client. No API keys or authentication needed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eliasbiondo--reddit-mcp-server/badge.svg)](/listings/eliasbiondo--reddit-mcp-server)

HTML

<a href="/listings/eliasbiondo--reddit-mcp-server"><img src="/api/listings/eliasbiondo--reddit-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

2.1. Using `uvx` (recommended)

The fastest way to run the server β€” no clone needed:

# 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

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

Run the server:

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

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

Cursor

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

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

From source (any MCP client)

{
  "mcpServers": {
    "reddit": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/reddit-mcp-server",
        "run", "reddit-no-auth-mcp-server"
      ]
    }
  }
}

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 339 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Reddit MCP Server
  2. [![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/)
  3. [![License: MIT](https://img.shields.io/github/license/eliasbiondo/reddit-mcp-server?cacheSeconds=3600)](https://github.com/eliasbiondo/reddit-mcp-server/blob/main/LICENSE)
  4. A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that
  5. provides AI assistants with access to Reddit data. Built on top of
  6. [redd](https://github.com/eliasbiondo/redd). It works without API keys where
  7. Reddit allows anonymous access, and can use optional
  8. [Reddit OAuth credentials](#41-reddit-api-credentials-optional) where it doesn't.
  9. https://github.com/user-attachments/assets/af8ae52c-f9f3-4d04-80d5-4be0dfa61b0f
  10. ---
  11. ## Table of Contents
  12. 1. [Features](#1-features)
  13. 2. [Quick Start](#2-quick-start)
  14. 3. [Available Tools](#3-available-tools)
  15. 4. [Configuration](#4-configuration)
  16. 5. [Architecture](#5-architecture)
  17. 6. [Contributing](#6-contributing)
  18. 7. [License](#7-license)
  19. ---
  20. ## 1. Features
  21. - πŸ” **Search** β€” Search all of Reddit or within a specific subreddit
  22. - πŸ“° **Subreddit Posts** β€” Browse hot, top, new, or rising posts from any subreddit
  23. - πŸ“– **Post Details** β€” Get full post content with nested comment trees
  24. - πŸ‘€ **User Activity** β€” View a user's recent posts and comments
  25. - πŸ“ **User Posts** β€” Get a user's submitted posts
  26. No browser required, and API keys are optional. Reddit now blocks unauthenticated
  27. requests from many networks (you'll see `HTTP 403 ... blocked by network
  28. security`). If that happens to you, add
  29. [Reddit API credentials](#41-reddit-api-credentials-optional).
  30. ---
  31. ## 2. Quick Start
  32. ### 2.1. Using `uvx` (recommended)
  33. The fastest way to run the server β€” no clone needed:
  34. ```bash
  35. # stdio transport (default, for Claude Desktop / Cursor / etc.)
  36. uvx reddit-no-auth-mcp-server
  37. # HTTP transport
  38. uvx reddit-no-auth-mcp-server \
  39. --transport streamable-http \
  40. --port 8000
  41. ```
  42. ### 2.2. From source
  43. ```bash
  44. git clone https://github.com/eliasbiondo/reddit-mcp-server.git
  45. cd reddit-mcp-server
  46. uv sync
  47. ```
  48. Run the server:
  49. ```bash
  50. # stdio transport (default)
  51. uv run reddit-no-auth-mcp-server
  52. # HTTP transport
  53. uv run reddit-no-auth-mcp-server \
  54. --transport streamable-http \
  55. --port 8000
  56. ```
  57. ### 2.3. MCP Client Configuration
  58. #### Claude Desktop
  59. Add to your `claude_desktop_config.json`:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "reddit": {
  64. "command": "uvx",
  65. "args": ["reddit-no-auth-mcp-server"]
  66. }
  67. }
  68. }
  69. ```
  70. #### Cursor
  71. Add to your `.cursor/mcp.json`:
  72. ```json
  73. {
  74. "mcpServers": {
  75. "reddit": {
  76. "command": "uvx",
  77. "args": ["reddit-no-auth-mcp-server"]
  78. }
  79. }
  80. }
  81. ```
  82. #### From source (any MCP client)
  83. ```json
  84. {
  85. "mcpServers": {
  86. "reddit": {
  87. "command": "uv",
  88. "args": [
  89. "--directory", "/path/to/reddit-mcp-server",
  90. "run", "reddit-no-auth-mcp-server"
  91. ]
  92. }
  93. }
  94. }
  95. ```
  96. ---
  97. ## 3. Available Tools
  98. | Tool | Description | Key Arguments | Returns |
  99. |------|-------------|---------------|---------|
  100. | `search` | Search Reddit for posts | `query`, `limit`, `sort` | `{"results": [...]}` |
  101. | `search_subreddit` | Search within a subreddit | `subreddit`, `query`, `limit`, `sort` | `{"results": [...]}` |
  102. | `get_post` | Get post details + comment tree | `permalink` | post object |
  103. | `get_subreddit_posts` | Get subreddit listing | `subreddit`, `limit`, `category`, `time_filter` | `{"posts": [...]}` |
  104. | `get_user` | Get user's activity feed | `username`, `limit` | `{"items": [...]}` |
  105. | `get_user_posts` | Get user's submitted posts | `username`, `limit`, `category`, `time_filter` | `{"posts": [...]}` |
  106. Every tool returns a JSON object (never a bare array) that matches its advertised
  107. `outputSchema`, so MCP-to-OpenAPI bridges such as
  108. [mcpo](https://github.com/open-webui/mcpo) / Open WebUI can validate the response.
  109. ### Tool Details
  110. #### `search`
  111. Search all of Reddit for posts matching a query.
  112. ```
  113. query: "python async programming"
  114. limit: 10
  115. sort: "relevance" # relevance, hot, top, new, comments
  116. ```
  117. #### `search_subreddit`
  118. Search within a specific subreddit.
  119. ```
  120. subreddit: "Python"
  121. query: "web scraping"
  122. limit: 10
  123. sort: "top"
  124. ```
  125. #### `get_post`
  126. Get full details of a Reddit post including its comment tree.
  127. ```
  128. permalink: "/r/Python/comments/abc123/my_post/"
  129. ```
  130. #### `get_subreddit_posts`
  131. Get posts from a subreddit listing.
  132. ```
  133. subreddit: "MachineLearning"
  134. limit: 25
  135. category: "hot" # hot, top, new, rising
  136. time_filter: "week" # hour, day, week, month, year, all
  137. ```
  138. #### `get_user`
  139. Get a user's recent public activity (posts and comments).
  140. ```
  141. username: "spez"
  142. limit: 10
  143. ```
  144. #### `get_user_posts`
  145. Get a user's submitted posts.
  146. ```
  147. username: "spez"
  148. limit: 10
  149. category: "top" # hot, top, new
  150. time_filter: "all" # hour, day, week, month, year, all
  151. ```
  152. ---
  153. ## 4. Configuration
  154. All settings can be configured via environment variables:
  155. | Variable | Default | Description |
  156. |----------|---------|-------------|
  157. | `REDDIT_TRANSPORT` | `stdio` | MCP transport (`stdio`, `streamable-http`) |
  158. | `REDDIT_HOST` | `127.0.0.1` | Host for HTTP transport |
  159. | `REDDIT_PORT` | `8000` | Port for HTTP transport |
  160. | `REDDIT_PATH` | `/mcp` | Path for HTTP transport |
  161. | `REDDIT_LOG_LEVEL` | `WARNING` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
  162. | `REDDIT_PROXY` | β€” | HTTP/HTTPS proxy URL |
  163. | `REDDIT_TIMEOUT` | `10.0` | Request timeout in seconds |
  164. | `REDDIT_THROTTLE_MIN` | `1.0` | Min delay between paginated requests (seconds) |
  165. | `REDDIT_THROTTLE_MAX` | `2.0` | Max delay between paginated requests (seconds) |
  166. | `REDDIT_CLIENT_ID` | β€” | Reddit app client ID; enables the OAuth API (see [4.1](#41-reddit-api-credentials-optional)) |
  167. | `REDDIT_CLIENT_SECRET` | β€” | Reddit app client secret (required together with `REDDIT_CLIENT_ID`) |
  168. | `REDDIT_USER_AGENT` | `python:reddit-no-auth-mcp-server:v<version> (...)` | User-Agent for OAuth API requests |
  169. CLI arguments take precedence over environment variables:
  170. ```bash
  171. uv run reddit-no-auth-mcp-server \
  172. --transport streamable-http \
  173. --port 9000 \
  174. --log-level DEBUG
  175. ```
  176. ### 4.1. Reddit API credentials (optional)
  177. By default the server makes anonymous requests to `www.reddit.com`, the same
  178. JSON endpoints a browser uses. Reddit blocks those from many networks: every tool
  179. then fails with `HTTP 403: You've been blocked by network security`. In that case,
  180. use Reddit's official OAuth API with app-only ("userless") credentials. No Reddit
  181. account login is involved; the server only reads public data.
  182. 1. Sign in to Reddit and open <https://www.reddit.com/prefs/apps>.
  183. 2. Click **create another app...**, choose **script**, give it a name, and enter
  184. any redirect URI (for example `http://localhost:8080`; it is not used).
  185. 3. Copy the **client ID** (the string under the app name) and the **secret**.
  186. 4. Pass them to the server as environment variables:
  187. ```json
  188. {
  189. "mcpServers": {
  190. "reddit": {
  191. "command": "uvx",
  192. "args": ["reddit-no-auth-mcp-server"],
  193. "env": {
  194. "REDDIT_CLIENT_ID": "your-client-id",
  195. "REDDIT_CLIENT_SECRET": "your-client-secret"
  196. }
  197. }
  198. }
  199. }
  200. ```
  201. With both variables set, the server gets an access token using the
  202. `client_credentials` grant, refreshes it automatically, and sends all requests
  203. to `https://oauth.reddit.com`. Leave both unset to keep anonymous access. Setting
  204. only one of them is an error.
  205. Notes:
  206. - Reddit's [API rules](https://github.com/reddit-archive/reddit/wiki/API)
  207. apply, including its OAuth rate limits (about 100 requests per minute per
  208. client). Depending on Reddit's current policy, a new app may need approval
  209. before its credentials work.
  210. - Reddit asks API clients to send a descriptive User-Agent. Set
  211. `REDDIT_USER_AGENT` to identify yourself, e.g.
  212. `python:my-reddit-mcp:v1.0 (by /u/your_username)`.
  213. - An `HTTP 401` error or "OAuth authentication failed" means the client ID or
  214. secret is wrong.
  215. ### 4.2. stdio and the FastMCP banner
  216. With the default `stdio` transport, the server turns off FastMCP's startup
  217. banner, so the only output is JSON-RPC on stdout and logs on stderr. Some MCP
  218. clients (notably on Windows) misbehave when the banner's box-drawing art shows up
  219. on stderr. For the HTTP transport the banner is still shown; set
  220. `FASTMCP_SHOW_SERVER_BANNER=false` to hide it there too.
  221. ---
  222. ## 5. Architecture
  223. This project follows **hexagonal architecture** (ports & adapters):
  224. ```
  225. src/reddit_mcp_server/
  226. β”œβ”€β”€ domain/ # Pure business logic, no framework imports
  227. β”‚ β”œβ”€β”€ exceptions.py # Domain exception hierarchy
  228. β”‚ └── value_objects.py # Immutable config objects
  229. β”œβ”€β”€ ports/ # Abstract interfaces (contracts)
  230. β”‚ β”œβ”€β”€ config.py # ConfigPort
  231. β”‚ └── reddit.py # RedditPort
  232. β”œβ”€β”€ application/ # Use cases (orchestration)
  233. β”‚ β”œβ”€β”€ search.py
  234. β”‚ β”œβ”€β”€ search_subreddit.py
  235. β”‚ β”œβ”€β”€ get_post.py
  236. β”‚ β”œβ”€β”€ get_user.py
  237. β”‚ β”œβ”€β”€ get_subreddit_posts.py
  238. β”‚ └── get_user_posts.py
  239. β”œβ”€β”€ adapters/
  240. β”‚ β”œβ”€β”€ inbound/ # Presentation layer
  241. β”‚ β”‚ β”œβ”€β”€ cli.py # CLI entry point
  242. β”‚ β”‚ β”œβ”€β”€ mcp_server.py
  243. β”‚ β”‚ β”œβ”€β”€ error_mapping.py
  244. β”‚ β”‚ β”œβ”€β”€ serialization.py
  245. β”‚ β”‚ └── mcp_tools/ # MCP tool definitions
  246. β”‚ └── outbound/ # Infrastructure layer
  247. β”‚ β”œβ”€β”€ env_config.py # ConfigPort implementation
  248. β”‚ └── redd_client.py # RedditPort implementation (wraps redd)
  249. └── container.py # DI composition root
  250. ```
  251. ---
  252. ## 6. Contributing
  253. Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
  254. guidelines on setting up the project, running tests, and submitting changes.
  255. ---
  256. ## 7. License
  257. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.