内容
# reddit-httpx 🤖
> 一个功能齐全的Reddit MCP服务器，使用浏览器cookie + TLS指纹伪装，让AI代理实现完整的Reddit自动化 — 浏览、发布、评论、投票、消息和审核。
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](LICENSE)
## 为什么存在
Reddit的官方API有严格的速率限制，需要OAuth应用注册，并限制许多操作。这个项目采用不同的方法：
- **浏览器cookie认证** — 无需API密钥，无需OAuth流程，无需范围限制
- **TLS指纹伪装** 通过 `curl_cffi` — 请求在网络级别上与真实的Chrome浏览器无法区分（JA3/JA4指纹匹配）
- **45个MCP工具** 涵盖完整的Reddit体验 — 从阅读到发布到审核
- **零浏览器自动化** — 纯HTTP，无Playwright/Selenium开销
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ AI 代理 (Claude 等) │
└──────────────────────────┬──────────────────────────────┘
│ MCP 协议 (stdio/HTTP)
┌──────────────────────────▼──────────────────────────────┐
│ FastMCP 服务器 │
│ ┌─────────┐ ┌────────┐ ┌──────┐ ┌─────┐ ┌──────────┐ │
│ │ 浏览 │ │ 搜索 │ │ 发布 │ │投票 │ │ 审核 │ │
│ │ 3 工具 │ │ 3 工具 │ │ 4 工具│ │ 3 工具 │ │ 6 工具 │ │
│ └────┬────┘ └───┬────┘ └──┬───┘ └──┬──┘ └────┬─────┘ │
│ └──────────┴─────────┴────────┴──────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ RedditAPI客户端 │ │
│ │ (curl_cffi + Chrome │ │
│ │ TLS 伪装) │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Cookie 管理器 │ │
│ │ (浏览器提取 │ │
│ │ + AES-CBC 解密) │ │
│ └────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
HTTPS (Chrome TLS)
│
┌──────────────────────────▼──────────────────────────────┐
│ www.reddit.com │
│ (看到一个正常的Chrome浏览器) │
└─────────────────────────────────────────────────────────┘
```
## 功能
### 12个类别中的45种工具
| 类别 | 工具 | 描述 |
|----------|-------|-------------|
| **浏览** | 3 | 子版块订阅源，首页，r/popular |
| **搜索** | 3 | 帖子，子版块，用户 |
| **帖子** | 2 | 获取帖子详情 + 评论树 |
| **用户** | 4 | 个人资料，帖子/评论历史，自己的账户 |
| **提交** | 4 | 文本帖子，链接帖子，编辑，删除 |
| **评论** | 4 | 评论，回复，编辑，删除 |
| **投票** | 3 | 点赞，点踩，取消投票 |
| **消息** | 3 | 收件箱，发送私信，标记已读 |
| **子版块** | 4 | 订阅，取消订阅，信息，我的订阅 |
| **保存** | 5 | 保存，取消保存，隐藏，取消隐藏，获取保存的 |
| **账户** | 4 | 账户信息，朋友管理 |
| **审核** | 6 | 删除，批准，区分，置顶，锁定 |
### 防检测
- **TLS 指纹**：`curl_cffi` 模仿 Chrome 的确切 TLS 握手（JA3 哈希与真实 Chrome 匹配）
- **基于 Cookie 的身份验证**：使用与浏览器相同的会话 Cookie — Reddit 看到的流量相同
- **无 OAuth 指纹**：避免 `oauth.reddit.com` 端点，该端点会标记自动化客户端
- **逼真的头部**：完整的 Chrome 用户代理，适当的 Accept 头部，X-Requested-With
### Cookie 提取
自动从以下浏览器提取和解密 Reddit Cookie：
- **Brave** (Linux/macOS)
- **Chrome** (Linux/macOS)
- **Firefox** (Linux/macOS)
- **Edge** (Linux/macOS)
处理 Chromium 的 AES-128-CBC Cookie 加密（Linux 上使用 `saltysalt` 进行 PBKDF2 密钥派生）。
## 快速入门
### 安装
```bash
# 克隆
git clone https://github.com/ishan-parihar/reddit-httpx.git
cd reddit-httpx
# 安装
pip install -e .
# 或使用开发依赖项
pip install -e ".[dev]"
```
### 身份验证
```bash
# 从浏览器导入 Cookie（交互式）
reddit-mcp --login
# 检查状态
reddit-mcp --status
# 输出：
# authenticated: True
# cookies_count: 8
# has_token: True
```
或通过环境变量设置 Cookie:
```bash
export REDDIT_COOKIES='{"reddit_session": "...", "token_v2": "..."}'
```
### 运行 MCP 服务器
```bash
# stdio 传输（适用于 Claude Desktop、Cursor 等）
reddit-mcp
# HTTP 传输（适用于远程客户端）
reddit-mcp --transport streamable-http --port 8000
```
### MCP 客户端配置
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"reddit": {
"command": "reddit-mcp",
"args": []
}
}
}
```
**Cursor / VS Code** (`.cursor/mcp.json`)：
```json
{
"mcpServers": {
"reddit": {
"command": "reddit-mcp",
"transportType": "stdio"
}
}
}
```
## 使用示例
连接后，AI 代理可以：
```
"浏览 r/programming 本周的热门帖子"
→ reddit_browse_subreddit(subreddit="programming", sort="top", time_filter="week")
"搜索有关 Rust async 的帖子"
→ reddit_search_posts(query="rust async", limit=10)
"获取 u/spez 的个人资料"
→ reddit_get_user_profile(username="spez")
"发布到 r/test"
→ reddit_submit_text_post(subreddit="test", title="Hello", text="World")
"为该帖子点赞"
→ reddit_upvote(thing_id="t3_abc123")
"回复该评论"
→ reddit_reply(comment_id="t1_xyz789", text="Great point!")
```
## 项目结构
```
reddit-httpx/
├── pyproject.toml # 依赖项和入口点
├── reddit_mcp_server/
│ ├── cli_main.py # CLI：--login，--logout，--status，--transport
│ ├── server.py # FastMCP 服务器 + 工具注册
│ ├── scraping/
│ │ └── api_client.py # RedditAPI客户端（curl_cffi，重试，速率限制）
│ ├── cookie_import.py # 浏览器 Cookie 提取 + AES 解密
│ ├── session_state.py # Cookie 持久性（~/.reddit-mcp/）
│ ├── authentication.py # 会话验证
│ ├── bootstrap.py # 启动初始化
│ ├── dependencies.py # 延迟客户端单例
│ ├── constants.py # URL，超时，用户代理
│ ├── exceptions.py # 错误层次结构
│ ├── error_handler.py # 集中错误处理
│ ├── sequential_middleware.py # 逐工具执行的中间件
│ └── tools/ # 12 个工具模块，总共 45 个工具
│ ├── browse.py # 子版块/首页浏览
│ ├── search.py # 搜索帖子/子版块/用户
│ ├── posts.py # 帖子详情 + 评论
│ ├── user.py # 用户个人资料和历史
│ ├── submit.py # 创建/编辑/删除帖子
│ ├── comments.py # 评论/回复/编辑/删除
│ ├── vote.py # 点赞/点踩/取消投票
│ ├── messaging.py # 私信和收件箱
│ ├── subreddit.py # 订阅/取消订阅
│ ├── save.py # 保存/隐藏帖子
│ ├── account.py # 账户和朋友
│ └── moderation.py # 审核操作
└── PLAN.md # 架构和实现计划
```
## 技术细节
### 为什么选择 curl_cffi 而不是 httpx/requests？
Reddit 使用 TLS 指纹检测自动化客户端。标准的 Python HTTP 库（httpx，requests，aiohttp）具有独特的 TLS 握手，与真实浏览器不同。`curl_cffi` 封装 libcurl，提供浏览器伪装 — 它复制 Chrome 的确切：
- TLS 扩展和排序
- ALPN 协议
- 密码套件首选项
- JA3/JA4 指纹哈希
这使得请求在加密方面与真实的 Chrome 浏览器无法区分。
### 为什么选择浏览器 Cookie 而不是 OAuth？
| | 浏览器 Cookie | OAuth API |
|---|---|---|
| 速率限制 | 浏览器级别（慷慨） | 60 req/min（严格） |
| 范围 | 完全访问 | 由范围限制 |
| 注册 | 无需注册 | 需要应用注册 |
| 2FA 账户 | 有效 | 无效 |
| 检测风险 | 最小（看起来像浏览器） | 标记为机器人 |
### 错误处理
- **429 速率限制** → 具有可配置睡眠的指数退避
- **401/403 身份验证** → 清晰的错误消息，指向 `--login`
- **500 服务器** → 3 次重试，带有退避
- **会话过期** → 检测到并清晰地报告
## 开发
```bash
# 安装开发依赖项
pip install -e ".[dev]"
# 检查代码风格
ruff check reddit_mcp_server/
# 格式化代码
ruff format reddit_mcp_server/
```
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `REDDIT_COOKIES` | Cookie 的 JSON 字典（ `--login` 的替代方案） | — |
| `REDDIT_MCP_PROFILE_DIR` | 配置目录 | `~/.reddit-mcp` |
| `REDDIT_MCP_LOG_LEVEL` | 日志级别 | `INFO` |
## 许可证
MIT
## 致谢
- [curl_cffi](https://github.com/yifeikong/curl_cffi) — 浏览器级别的 TLS 伪装
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP 服务器框架
- [Model Context Protocol](https://modelcontextprotocol.io) — 协议标准
---
由 [Ishan Parihar](https://github.com/ishan-parihar) 开发 — 如果您觉得这很有用， [考虑支持](https://rzp.io/rzp/ishan-parihar)
