reddit-mcp

面向 Cursor / Grok Bot connect-card OAuth 的只读 Reddit 数据 API MCP 连接器。 作为 Cloudflare Worker 运行，支持 MCP Streamable HTTP，并将调用方的 Authorization: Bearer 令牌透传至 https://oauth.reddit.com。

仓库：https://github.com/pmsorhaindo/reddit-mcp

架构

Cursor / Grok Bot
   │  OAuth (connect-card) against Reddit authorize/token
   │  then MCP JSON-RPC with Bearer access token
   ▼
Cloudflare Worker (this repo)
   │  POST /mcp  → tools/list, tools/call
   │  GET  /.well-known/oauth-*  → discovery pointing at Reddit
   ▼
https://oauth.reddit.com  (User-Agent from env, Bearer passthrough)

为什么采用极简 JSON-RPC（而不是完整的 MCP SDK）？

@modelcontextprotocol/sdk 历来面向 Node.js 传输层。本 Worker 实现了 Workers-native、轻依赖的 Streamable HTTP JSON-RPC 接口（initialize / tools/list / tools/call），匹配 Cursor/Grok 的工具调用需求，且无需 Durable Objects 或会话存储。这正好契合 bearer 透传：Worker 从不持有 Reddit 刷新令牌。

工具

所有工具均返回精简 JSON（截断文本字段）。limit 默认值为 25，上限为 100。

速率限制

• 对 Reddit 的出站调用会在每个 Worker isolate（promise 链）内串行化。

• 在下次调用之前会遵循响应中的 X-Ratelimit-Remaining / X-Ratelimit-Reset。

• HTTP 429 / 503 会触发有界重试，并配合 Retry-After 或指数退避。

密钥卫生

切勿提交真实密钥。

• 健壮的 .gitignore 涵盖 .env、.dev.vars、.wrangler/、node_modules/、dist/、credentials*.json、.mcp-auth/。

• 只有示例环境文件会被提交：.dev.vars.example、.env.example。

• wrangler.toml 中没有内联机密。

• 错误和 console 日志永远不会包含 Authorization 头、待表达 token 或机密环境变量值。

• 工具错误负载仅包含状态/消息——不包含可能回显凭据的上游响应主体。

Related MCP server: reddit-mcp

Reddit 应用设置

1. 在 https://www.reddit.com/prefs/apps 创建 Reddit 应用（根据你的客户端选择 web app 或 installed app 类型）。

2. 添加重定向 URI：

   • http://localhost:8787/callback — 本地 wrangler / 手动测试

   • https://www.cursor.com/agents/mcp/oauth/callback — Cursor connect-card

3. 请求授权范围（在 Reddit 授权 URL 中以逗号分隔）：

   • identity,read,mysubreddits,history

4. 请记下 client_id / client_secret 以供 OAuth 客户端（Cursor / 你的凭据管理器）使用。不要将它们放入本仓库或 wrangler.toml 中。

OAuth 发现假设

• /.well-known/oauth-authorization-server 会公布：

  • authorization_endpoint：https://www.reddit.com/api/v1/authorize

  • token_endpoint：https://www.reddit.com/api/v1/access_token

• 本 Worker 不会执行授权码交换，也不会存储刷新令牌。

• Cursor/Grok 使用你在客户端中配置的 Reddit 应用凭据与 Reddit 完成 OAuth，然后在 MCP 请求中发送 Authorization: Bearer <access_token>。

• 元数据中的 issuer 是本 Worker 的来源（origin），以便 MCP 客户端可以从 MCP 基础 URL 发现文档；但授权和获取令牌仍在 Reddit 上进行。

• Reddit 授权范围习惯上用逗号分隔写在 authorize URL 上——客户端必须相应地将多个 scope 拼接起来。

Cloudflare 部署

先决条件：Node 22+、Cloudflare 账号、已登录的 Wrangler（npx wrangler login）。

git clone https://github.com/pmsorhaindo/reddit-mcp.git
cd reddit-mcp
npm install

# Local secrets (gitignored)
cp .dev.vars.example .dev.vars
# edit USER_AGENT — must identify you per Reddit API rules

npm run typecheck
npm run dev          # http://127.0.0.1:8787

# Production secret (not committed)
npx wrangler secret put USER_AGENT
npm run deploy

USER_AGENT 示例格式（仅为占位符）：

cloudflare-worker:reddit-mcp:0.1.0 (by /u/YOUR_REDDIT_USERNAME)

部署后记下 workers.dev 或你自己的自定义域名 URL，例如 https://reddit-mcp.<account>.workers.dev。

添加 MCP 服务器（Cursor / Grok）

使用 AddMcpServer（或等效的 connect-card）进行配置：

客户端应使用你的 Reddit 应用 client_id / client_secret，以及上面列出的 Cursor 重定向 URI。完成认证后，MCP 工具调用必须以 Bearer 头的形式包含 Reddit 访问令牌；本 Worker 会将其原样转发给上游。

冒烟测试

在本地替换 $BASE 和 $TOKEN ——切勿提交令牌。

BASE=http://127.0.0.1:8787
TOKEN=reddit_access_token_here

# Health
curl -sS "$BASE/health"

# OAuth metadata
curl -sS "$BASE/.well-known/oauth-authorization-server"
curl -sS "$BASE/.well-known/oauth-protected-resource"

# MCP initialize
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'

# tools/list
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# tools/call get_me (requires valid Bearer)
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_me","arguments":{}}}'

预期结果：JSON-RPC 结果；get_me 返回精简的个人资料字段。缺少 Bearer 时 → 返回 JSON-RPC 错误 Unauthorized，且不泄露任何请求头。

脚本

超出范围

• 发帖、投票、私信、审核或 Ads API

• 在 Worker 上存储 Reddit 刷新令牌或客户端机密

• 在 /callback 上执行 OAuth 授权码交换

• 完整的 MCP 资源 / 提示 / 采样 / elicitation 会话

• 多租户令牌保险库 / Durable Object 会话存储

• 保证跨 isolate 的全局速率限制协调（限制按 isolate + Reddit 响应头）

许可证

私有 / 未发布，除非你另外添加许可证文件。