用途
freshrss-mcp 是一个 Model Context Protocol（MCP）服务器，用于连接自托管的 RSS 与 Atom 订阅聚合器 FreshRSS。它让 Claude Code、Claude Desktop、Codex 等 MCP 客户端能够操作用户的订阅内容：查看哪些未读、阅读文章、进行标记，以及管理订阅源和分类。
主要能力
- 通过 FreshRSS 在 /api/greader.php 暴露的 Google Reader 兼容 API 进行通信。
- 默认提供十六个工具，覆盖订阅源、分类、标签、文章、已读与星标状态，以及 OPML 导入导出。
- 工具参数使用数字 feed id、分类与标签名称、ISO 日期和十进制文章 id，而不是 Google Reader API 的 stream 标识符和十六进制 item tag；返回纯文本而非原始 HTML。
- 支持通过 FRESHRSS_ALLOW_TOOLS 和 FRESHRSS_DENY_TOOLS 选择加载哪些工具，支持逗号分隔的工具名和以 * 结尾的整族匹配；essential 是精选的七个工具预设：list_feeds、list_categories、get_unread_counts、list_articles、get_articles、mark_articles、mark_all_as_read。
- 每个工具声明 outputSchema，并在文本块之外返回 structuredContent，便于客户端直接使用结果而无需解析文字。
- 报告订阅内容的工具会携带 untrusted: true 和 source: "freshrss" 字段。
- 提供 Docker 镜像，发布 linux/amd64 与 linux/arm64，附带 SBOM 和构建来源信息，以非特权 node 用户运行，镜像内不含 npm。
- 可通过 mcp-hub 让无法启动本地进程的客户端（如 ChatGPT connectors、网页版 Claude、Cursor、LibreChat）经 Streamable HTTP 访问，其 /hub 端点用六个元工具替代所有服务器的工具。
使用方式
需要 Node.js 22 或更高版本，以及一个启用了 API 的 FreshRSS 实例（开发针对 1.29 版本）。启用步骤：在 Settings → Authentication 中勾选 "Allow API access"；在 Settings → Profile → API management 中为用户设置 API 密码，该密码与网页登录密码不同。服务器在没有凭据时也能启动，以便工具保持可列出，但每次调用都会失败并给出这些设置说明。
通过 mcp-hub 使用时，其 /config/mcp.json 采用 Claude Code 的格式，可直接沿用已有条目。
适用场景
适合使用自托管 FreshRSS 并希望通过 MCP 客户端以对话方式管理订阅、阅读和整理文章的用户。也适合需要让无法启动本地进程的客户端接入的场景，此时可借助 mcp-hub。
限制与安全设计
- 不提供全文搜索：FreshRSS 的 Google Reader API 端点只按 stream、已读状态和日期过滤，因此 list_articles 没有 query 参数，需用 feed_id / category 和 since / until 缩小范围后自行过滤返回的文章。FreshRSS 网页界面的搜索背后没有 API 端点。
- 不返回原始 HTML：文章正文转换为纯文本，并按篇和按响应设上限。
- 文章文本属于不可信输入：所有来自 FreshRSS 的内容均由互联网上的第三方撰写，携带文章文本、标题或订阅源名称的响应会被明确标记为数据而非指令。
- 五个不可逆工具会先询问真人：mark_all_as_read、unsubscribe_feed、delete_category_or_label、import_opml，以及 mark_articles（仅当即将把内容标记为已读时）。在客户端支持 MCP elicitation 时弹出真实对话框，模型无法代为回答；不支持对话框时回退为绑定到确切目标的一次性令牌，并如实说明。
- 响应预算：FreshRSS 每篇文章最多返回 500 000 字符的 HTML；文章文本转换为纯文本，按篇和按响应预算设上限，列表中的文章文本为可选。预算按读取的标记量而非输出的文本量计费。
- 凭据只读取一次，随后从 process.env 中移除且不写入磁盘；请求不跟随重定向；放宽的 TLS 验证仅限该连接。
- feed URL 会被脱敏：FreshRSS 将 HTTP 认证订阅源存为 https://user:password@host/feed，userinfo 部分在进入工具结果或 OPML 导出前被剥离。
- subscribe_feed 和 import_opml 拒绝内部目标：回环和链路本地地址（包括云元数据端点）会被拒绝，地址按数值比较，主机名在接受前先解析；私有局域网地址仍允许。import_opml 拒绝 <!DOCTYPE>。
- FRESHRSS_READ_ONLY=true 时完全不注册写入工具，而不是在调用时拒绝。
完整指南、工具参考和安全说明见 freshrss-mcp.ni-c.de（源码在 docs/）。项目采用 MIT 许可，作者 Willi Thiel。
