# Reddit MCP Server 🤖

> 让AI助手访问Reddit的神奇工具！一个基于MCP (Model Context Protocol)的Reddit数据访问服务。

## ✨ 功能特性

这个MCP服务器让你的AI助手（比如Claude）能够：

- 🔐 **安全认证** - 使用Reddit官方OAuth进行安全连接
- 👤 **用户信息** - 获取用户配置文件、karma、活动概览
- 📰 **子版块** - 浏览子版块信息、帖子列表、规则
- 💬 **帖子和评论** - 查看帖子详情、评论树
- 🔍 **搜索** - 跨Reddit搜索帖子
- ⚡ **智能分页** - 支持分页和大量数据的优雅处理

**注意**：当前版本为第一阶段，只实现只读操作。暂不支持发布帖子或评论（在后续版本中添加）。

## 📋 前置要求

- Python 3.11 或更高版本
- 一个Reddit账号
- Reddit开发者应用凭证（见下方配置指南）

## 🚀 快速开始

### 1. 克隆或下载项目

```bash
git clone <your-repo-url>
cd reddit-mcp
```

### 2. 创建虚拟环境（推荐）

```bash
# 使用uv（推荐，速度更快）
uv venv
source .venv/bin/activate

# 或使用传统方法
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate     # Windows
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置Reddit应用凭证

这是最重要的一步！你需要创建一个Reddit开发者应用来获取API凭证：

#### 步骤1：创建Reddit应用

1. 访问 [Reddit App Preferences](https://www.reddit.com/prefs/apps)
2. 滚动到页面底部的 "developed apps" 部分
3. 点击 "create another app..." 或 "create app"
4. 填写表单：
   - **name**: 随便起个名字，比如 `reddit-mcp-server`
   - **type**: 选择 `script`（这很重要！）
   - **description**: 填写或不填都行
   - **about url**: 可以填你的GitHub仓库链接或不填
   - **redirect uri**: 留空即可
5. 点击 "create app"

#### 步骤2：获取凭证

创建成功后，你会看到：
- **client_id**: 字符串（14个字符）在app名称下方
- **client_secret**: 字符串（27个字符）紧挨着 "secret" 文字旁边
- 注意：不要混淆成 "app id" 或其他字段！

#### 步骤3：配置环境变量

复制 `.env.example` 为 `.env` 并填入你的凭证：

```bash
cp .env.example .env
```

然后编辑 `.env` 文件：

```env
REDDIT_CLIENT_ID=你的14字符client_id
REDDIT_CLIENT_SECRET=你的27字符client_secret
REDDIT_USER_AGENT=script:reddit-mcp:1.0.0:你的Reddit用户名
REDDIT_USERNAME=你的Reddit用户名
REDDIT_PASSWORD=你的Reddit密码
```

### 5. 测试连接

你可以使用MCP客户端（如Claude Desktop）测试连接，或运行示例脚本：

```bash
# 测试连接（需要先配置环境变量）
python -c "from src.reddit_mcp.server import main; main()"
```

## 🔧 配置Claude Desktop

要在Claude Desktop中使用这个MCP服务器，你需要编辑配置文件：

### macOS/Linux

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "reddit": {
      "command": "python",
      "args": ["/绝对路径/to/reddit-mcp/src/reddit_mcp/server.py"],
      "env": {
        "REDDIT_CLIENT_ID": "你的client_id",
        "REDDIT_CLIENT_SECRET": "你的client_secret",
        "REDDIT_USER_AGENT": "script:reddit-mcp:1.0.0:你的用户名",
        "REDDIT_USERNAME": "你的用户名",
        "REDDIT_PASSWORD": "你的密码"
      }
    }
  }
}
```

### Windows

编辑 `%APPDATA%\Claude\claude_desktop_config.json`（路径类似）

## 🛠️ 可用工具

### 连接和用户信息
- `check_connection` - 检查Reddit API连接状态
- `get_current_user` - 获取当前认证用户的信息
- `get_user_karma` - 获取用户的karma明细
- `get_user_overview` - 获取用户最近的活动

### 子版块
- `get_subreddit_info` - 获取子版块详细信息
- `get_subreddit_posts` - 获取子版块的帖子列表（支持hot/new/top/rising）
- `get_subreddit_rules` - 获取子版块规则

### 帖子和评论
- `get_post_details` - 获取帖子的完整详情
- `get_post_comments` - 获取帖子的评论树
- `search_posts` - 搜索帖子

## 📖 使用示例

### 基础使用

1. **检查连接**：
   ```
   "请帮我检查一下Reddit API的连接状态"
   ```

2. **查看用户信息**：
   ```
   "获取我的Reddit用户信息和karma"
   ```

3. **浏览子版块**：
   ```
   "获取r/python子版块的热门帖子"
   ```

4. **搜索帖子**：
   ```
   "搜索关于MCP协议的帖子"
   ```

### 高级用法

**带分页的子版块浏览**：
```
"获取r/technology的新帖子，限制20条，返回详细格式"
```

**查看特定帖子**：
```
"获取这个帖子的详情：https://www.reddit.com/r/python/comments/xyz123"
```

**查看评论**：
```
"获取这个帖子的评论树，深度限制为3层"
```

## ⚠️ 常见问题

### 1. 认证失败：401 Unauthorized

**原因**：凭证错误或应用类型不对

**解决方法**：
- 确保client_id和client_secret填写正确（没有多余的空格）
- 确保创建的应用类型是 `script` 而不是 `web` 或 `installed app`
- 检查用户名和密码是否正确
- Reddit用户名区分大小写！

### 2. 速率限制错误：429 Too Many Requests

**原因**：请求太频繁，超过了Reddit API限制

**解决方法**：
- 这个服务器已经内置了速率限制处理，会自动重试
- 如果频繁遇到，可能需要减少请求频率
- Reddit的速率限制通常是60秒内最多600次请求

### 3. 子版块不存在：404 Not Found

**原因**：子版块名称错误或已删除

**解决方法**：
- 确认子版块名称拼写正确（包括大小写）
- 某些私有或已删除的子版块无法访问

### 4. 找不到模块错误

**原因**：Python环境配置问题

**解决方法**：
```bash
# 确保在虚拟环境中
source .venv/bin/activate  # Linux/Mac

# 重新安装依赖
pip install -r requirements.txt
```

## 🔒 安全注意事项

- ✅ **不要**将 `.env` 文件提交到版本控制系统（已添加到.gitignore）
- ✅ 凭证通过环境变量存储，不会硬编码在代码中
- ✅ 当前版本只实现只读操作，不会修改你的Reddit数据
- ⚠️ 请妥善保管你的Reddit应用凭证，不要分享给他人

## 📚 技术栈

- **Python 3.11+** - 编程语言
- **PRAW** - Python Reddit API Wrapper（Reddit API客户端）
- **MCP Python SDK** - MCP协议实现
- **Pydantic v2** - 数据验证和序列化
- **python-dotenv** - 环境变量管理

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

## 🙏 致谢

- Reddit官方API文档
- PRAW开发团队
- MCP (Model Context Protocol) 社区

---

**有问题？** 请查看GitHub Issues或创建新的Issue。祝你使用愉快！🎉