Reddit MCP Server 🤖

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

✨ 功能特性

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

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

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

📋 前置要求

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

🚀 快速开始

1. 克隆或下载项目

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

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

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

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

3. 安装依赖

pip install -r requirements.txt

4. 配置Reddit应用凭证

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

步骤1：创建Reddit应用

1. 访问 Reddit App Preferences
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 并填入你的凭证：

cp .env.example .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）测试连接，或运行示例脚本：

# 测试连接（需要先配置环境变量）
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：

{
  "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环境配置问题

解决方法：

# 确保在虚拟环境中
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。祝你使用愉快！🎉