NewsBlur 三件套实战指南：CLI 命令行工具、AI Skill 与 MCP Server 完整接入手册

• 后端
• 前端
• 社交
• 人工智能

本文基于 NewsBlur 官方博客发布的技术公告《The NewsBlur CLI Tool, AI Skill, and MCP Server》整理并扩充。NewsBlur 一直以 REST API 驱动其 Web、iOS 与 Android 全端产品，本文介绍的三件新工具（终端 CLI、AI 技能、MCP 服务器）把同样的能力下沉到终端与 AI Agent 生态中。读完本文，你将掌握三者的安装、登录、常用命令、配置方式与安全设计，并能依据自己的工具链（终端脚本、Claude Code、Claude Desktop、Codex、Cursor、Windsurf）选择最合适的接入方案。

背景：为什么 NewsBlur 需要三件新工具

NewsBlur 的每一项功能（Web 应用、iOS 应用、Android 应用）都运行在其统一的 API 之上，但 API 是面向开发者的。为了让普通用户、脚本编写者和 AI Agent 都能直接操作账户，官方一次性发布了三种互补的交互方式：

1. CLI 工具——把整个 NewsBlur 放进终端，适合脚本化与日常操作；
2. AI Skill——教 AI Agent 学会 CLI 的每个命令，上下文窗口占用极低；
3. MCP Server——把任何 MCP 兼容的 AI Agent 直接连接到你的 NewsBlur 账户。

三者共享同一个核心约束：需要 Premium Archive 或 Premium Pro 订阅 才能使用。首次使用时会弹出浏览器窗口进行 OAuth 授权，令牌保存在本地，你可以随时在账户中撤销访问权限。

在仓库中，这三者的实现集中在 newsblur_mcp/ 目录：CLI 与 MCP Server 打包在同一个名为newsblur-cli的 Python 发行版中（参见 pyproject.toml），AI Skill 则以独立技能包形式分发。

快速上手：三种接入方式的开箱体验

CLI 工具——安装并登录：

uv pip install newsblur-cli newsblur auth login

AI Skill——安装到 Claude Code、Cursor、Windsurf 或任何兼容 Skills 标准的工具：

npx skills add samuelclay/newsblur-cli-skill

MCP Server——从 Claude Code、Claude Desktop、Codex 或任何 MCP 客户端连接：

claude mcp add --transport http newsblur https://newsblur.com/mcp/

三条命令全部就绪后，你就能在终端里读订阅源、让 AI 代理帮你管理故事与分类器，或把账户直接暴露给任意 MCP 客户端。

CLI 工具：把整个 NewsBlur 搬进终端

CLI 由 newsblur_mcp/newsblur_mcp/cli/init.py 定义，基于 Typer 框架构建。入口脚本在 pyproject.toml 中注册为newsblur = "newsblur_mcp.cli:app"。命令按功能划分为 7 个命令组（auth、stories、feeds、actions、train、discover以及顶层快捷命令account/briefing/read/save/unsave/share），覆盖了你在 NewsBlur 中能做的几乎所有操作。完整命令清单见仓库内 newsblur_mcp/README.md。

读取故事：从订阅源、文件夹或全量

newsblur stories list # 未读故事 newsblur stories list --folder Tech --limit 5 # 按文件夹过滤 newsblur stories search "machine learning" # 全文搜索 newsblur stories saved --tag research # 按标签查看已保存故事 newsblur stories infrequent # 低频更新订阅源的故事 newsblur stories original 123:abc456 # 抓取文章原文全文

各子命令的底层实现可以在 newsblur_mcp/newsblur_mcp/cli/commands/stories.py 中追踪：stories list支持--folder、--feed（逗号分隔的 feed ID）、--filter（unread/all/focus/starred）、--order、--page、--limit（默认 12，上限 50）等参数；stories original通过/rss_feeds/original_text接口获取原文并用html_to_text转换。从源码结构看，CLI 与 MCP Server 复用了同一套_get_stories、_get_saved_stories、_search_stories等核心函数（位于 newsblur_mcp/newsblur_mcp/tools/stories.py），因此两者行为一致。

获取 AI 策展的每日简报

newsblur briefing # 今日简报 newsblur briefing --limit 1 # 只要最新一条 newsblur briefing --json # 结构化输出

briefing默认返回 5 条简报，可通过--limit调整，使用render_briefing渲染（见 stories.py）。

管理订阅源与文件夹

newsblur feeds list # 全部订阅 newsblur feeds folders # 带计数的文件夹树 newsblur feeds add https://example.com # 订阅 newsblur feeds add https://blog.com -f Tech # 订阅到指定文件夹 newsblur feeds remove 42 # 退订 newsblur feeds organize move_feed --feed-id 42 --from News --to Tech

对故事执行操作

newsblur save 123:abc --tag ai --tag research # 保存并打标签 newsblur unsave 123:abc # 取消保存 newsblur read --feed 42 # 将某订阅源全部标记为已读 newsblur share 123:abc --comment "Worth reading"

训练智能分类器

newsblur train show --feed 42 # 查看当前训练规则 newsblur train like --feed 42 --author "Name" # 训练"喜欢" newsblur train dislike --feed 42 --tag sponsor # 训练"不喜欢"

发现新订阅源

newsblur discover search "machine learning" # 按主题搜索 newsblur discover similar --feed 42 # 找相似订阅源 newsblur discover trending # 热门订阅源

输出格式与自托管支持

每个命令都支持--json（结构化输出，可直接接jq或用于脚本）和--raw（纯文本）；另有全局--server标志指向自托管 NewsBlur 实例：

newsblur --server https://my-newsblur.example.com auth login newsblur briefing --json | jq '.items[0].section_summaries'

--server地址会持久化到~/.config/newsblur/config.json（见 newsblur_mcp/README.md 与 newsblur_mcp/newsblur_mcp/cli/auth.py），后续命令无需重复指定。

OAuth 登录的底层原理

newsblur auth login走的是 gh-auth-login 风格的本地回调流程（auth.py）：在127.0.0.1的随机端口启动临时 HTTP 服务器 → 打开浏览器跳转/oauth/authorize/（client_id=newsblur-cli、scope=read+write）→ 回调捕获授权码 → 在/oauth/token/换发 access token → 以0600权限保存到~/.config/newsblur/auth.json。令牌过期后会自动用 refresh token 刷新，登录回调最长等待 120 秒。

AI Skill：教你的 Agent 学会每个命令，且不烧光上下文窗口

CLI 本身已经很强大，但当你把命令交给 AI Agent 时，还要让它"知道有哪些命令可用"。NewsBlur CLI Skill 正是为此而生：它向 Agent 提供完整的命令参考——每个子命令、每个标志、每种输出格式。一条命令即可安装，之后 Agent 就能替你读订阅源、搜索故事、训练分类器、管理订阅。

npx skills add samuelclay/newsblur-cli-skill

npx skills add兼容任何支持 Skills 标准的工具：Claude Code、Cursor、Windsurf 以及更多。仓库中技能相关文档与 CLI 包同源，CLI 能力的完整描述见 newsblur_mcp/README.md。

Skill 相对 MCP Server 的最大优势是上下文效率。MCP Server 返回的原始 JSON 会直接进入 Agent 的上下文窗口：查询一次已保存的 ESP32 故事就会烧掉将近 40,000 个 token；而 Skill 改为运行 CLI，返回的是干净、格式化的文本。同一查询、同样结果，token 消耗约为三分之一。官方测试数据：MCP Server 查询已保存故事消耗39,553 tokens，经 Skill 走同一查询仅消耗11,735 tokens。

因此选择策略很清晰：

• 工具支持 Skills →用 Skill（上下文效率更高）；
• 只支持 MCP →用 MCP Server；
• 只想在终端脚本化操作 NewsBlur →直接用 CLI。

MCP Server：把账户直接接入任意 MCP 客户端

MCP（Model Context Protocol）是一个开放标准，让 AI Agent 连接外部工具与数据。通过 NewsBlur MCP Server，Claude、Codex、Cursor、Windsurf 以及任何 MCP 兼容 Agent 都能读你的订阅源、管理故事、训练分类器、整理订阅。

22 个工具，四大能力域

服务端暴露22 个工具，覆盖你在 NewsBlur 中的全部日常操作：

Reading（阅读）——列出带未读计数的订阅源与文件夹；从任意订阅源、文件夹或全部订阅一次性加载故事；按 unread/focus/starred 过滤；跨整个存档全文搜索；抓取原文全文；获取 AI 每日简报；浏览低频更新订阅源的故事。

Actions（操作）——按 hash、按订阅源、按文件夹标记已读；保存故事（支持标签、笔记、高亮）；订阅与退订；在文件夹间移动订阅源；重命名订阅源与文件夹；分享故事到你的 Blurblog。

Intelligence（智能）——查看全部订阅源的已训练分类器；按作者、标签、标题或正文训练"喜欢/不喜欢"；支持完整训练级别，包括可覆盖所有正向得分的新增super dislike（超级不喜欢）。

Discovery（发现）——按主题搜索新订阅源；查找与已关注订阅源相似的源；浏览热门订阅源。

客户端配置示例

Claude Code（命令行方式）：

claude mcp add --transport http newsblur https://newsblur.com/mcp/

Claude Desktop：在claude_desktop_config.json中加入：

{ "newsblur": { "type": "http", "url": "https://newsblur.com/mcp/" } }

Codex、Cursor 与 Windsurf 各有自己的配置格式，全部客户端设置说明详见 newsblur_mcp/README.md。

服务端实现要点

从 newsblur_mcp/newsblur_mcp/server.py 可以看到服务端基于FastMCP构建，以streamable-http传输协议运行（默认监听0.0.0.0:8099，端口由 settings.py 中MCP_PORT环境变量控制）。请求鉴权通过 OAuth 中间件完成：get_client()从请求上下文的AuthenticatedUser.access_token提取上游 Django OAuth 令牌（测试场景也可回退到Authorization: Bearer头），再用 newsblur_mcp/newsblur_mcp/client.py 中的NewsBlurClient调用 NewsBlur API。工具函数统一包了请求日志与用量上报（log_request/record_mcp_usage），并集成了 Sentry 错误追踪。全部工具定义分布在 tools/ 下的account、actions、archive、briefing、classifiers、discovery、feeds、notifications、social、stories十个模块中，配套测试覆盖见 newsblur_mcp/tests/（如 test_stories.py、test_actions.py、test_server.py）。

Readonly 模式：给 AI 加一道不可绕过的护栏

把 AI Agent 接入账户固然强大，但你可能想先从护栏开始。CLI 提供 readonly 模式，阻断一切写操作：不保存、不分享、不训练、不订阅、不标记已读。Agent 可以读订阅源、搜索故事，但改不了任何东西。

newsblur auth readonly --on

开启后，任何写命令都会返回错误而不是执行。

关键在关闭它的那一刻：关闭只读模式会把你登出，并强制你在浏览器里重新授权：

newsblur auth readonly --off # "You have been logged out and must re-authenticate." newsblur auth login

这是刻意为之的设计。从源码看（auth.py 中的set_readonly），当readonly被设为False时会同步delete_token()删除本地令牌——AI Agent 无法静默关闭只读然后开始写操作，只有坐在浏览器前的人类才能重新授权写权限。如果你把 CLI 交给 Agent 并希望它始终保持只读，它就会保持只读。newsblur auth status会显示当前账户、套餐等级（Free/Premium/Archive/Pro）、订阅数与只读状态，便于随时核对。

可用性与选择建议

CLI、AI Skill 与 MCP Server 现已面向Premium Archive 与 Premium Pro 订阅用户开放，完整文档见 newsblur_mcp/README.md。三者的取舍可以简单归纳为：

值得一提的是，若你想自托管整套环境，docker-compose.yml 与 newsblur_mcp/Dockerfile 提供了部署线索，而 MCP 的 OAuth 相关环境变量（MCP_OAUTH_CLIENT_ID、MCP_OAUTH_INTERNAL_URL等）在 settings.py 中均有默认值，可结合自托管实例按需覆盖。

• 后端
• 前端
• 社交
• 人工智能