# Reddit MCP Server

A Model Context Protocol server for reading Reddit data from public JSON endpoints.

## What It Does

This codebase currently implements a read-only Reddit server with five MCP tools:

- `search_subreddit`
- `get_subreddit_posts`
- `get_post_thread`
- `get_user_profile`
- `get_user_activity`

The server does not require Reddit authentication for the implemented tools.

## How It Works

- Uses `aiohttp` for async HTTP requests to Reddit's public `.json` endpoints.
- Reuses one shared client session and rotates User-Agent strings per request.
- Normalizes Reddit responses into compact post, comment, profile, and activity objects.
- Validates subreddit names, usernames, post IDs, sort values, and limits before making a request.

## Installation

```bash
pip install -e .
```

Requires Python 3.12 or newer.

## Run

```bash
reddit-mcp-server
```

Optional transports:

```bash
reddit-mcp-server --transport http
reddit-mcp-server --transport sse
reddit-mcp-server --transport streamable-http
reddit-mcp-server --log-level DEBUG
reddit-mcp-server --version
```

Default transport is `stdio`, which is the recommended mode for MCP clients.

## MCP Client Configuration

Example configuration:

```json
{
  "mcpServers": {
    "reddit": {
      "command": "reddit-mcp-server",
      "args": ["--transport", "stdio"]
    }
  }
}
```

## Tool Summary

| Tool | Purpose |
|------|---------|
| `search_subreddit` | Search posts within a subreddit by keyword |
| `get_subreddit_posts` | Fetch hot/new/top/rising posts from a subreddit |
| `get_post_thread` | Fetch a post and its top-level comments |
| `get_user_profile` | Fetch a user's public profile metadata |
| `get_user_activity` | Fetch a user's recent posts and/or comments |

## Repository Layout

```text
reddit_mcp_server/
├── server.py
├── cli_main.py
├── http_client.py
└── tools/
    └── read/
        ├── __init__.py
        ├── common.py
        ├── search_subreddit.py
        ├── get_subreddit_posts.py
        ├── get_post_thread.py
        ├── get_user_profile.py
        └── get_user_activity.py
```

## Documentation

- `API.md` contains the parameter and response reference for the implemented tools.

## Notes

- The server trims long post bodies and comment bodies to keep responses compact for LLM usage.