mcpField
F
freshrss

freshrss

github.com/wmy2981Productivity155 installsUpdated 5w ago
Repository

About freshrss

freshrss is a skill for working with subscriptions and articles through FreshRSS’s Google Reader-compatible API. It is intended for users of a self-hosted RSS reader and provides reading, search, and feed-management commands through a Python script.

Key features

  1. 01View recent, unread, and starred articles
  2. 02Filter articles by feed or category
  3. 03Search article titles or content
  4. 04Manage feeds and categories
  5. 05Mark articles read or starred
  6. 06Return results as JSON

Use cases

  1. 01Review unread FreshRSS articles
  2. 02Search subscribed articles for keywords
  3. 03Add, move, or remove feeds
  4. 04Find new feeds by topic

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wmy2981/skills --skill freshrss

After installing, type/freshrssin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.claude-plugin/
plugin.json
references/
api_doc.md
scripts/
.env.example
freshrss.py

Details

From the project README

FreshRSS

Self-hosted RSS reader accessed via Google Reader compatible API (GReader). All operations go through a single python script.

Execution Rule

Run the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.

Environment Variables

VariableDescription
FRESHRSS_URLBase URL (e.g. http://127.0.0.1:1180)
FRESHRSS_API_USERAPI username
FRESHRSS_API_PASSWORDAPI password

💡 Environment variables can be configured in ~/.wmyskills/.env (shared across skills) or scripts/.env (takes priority if present). The script loads them automatically.

Usage

python scripts/freshrss.py <command> [options]

Common options for reading commands: --count N (default 20), -v/--verbose (include summary text).

Reading Articles

Recent articles
python scripts/freshrss.py recent --count 10
python scripts/freshrss.py recent --count 5 -v    # with summary
Unread articles
python scripts/freshrss.py unread --count 20
Articles from a specific feed
python scripts/freshrss.py feed --url "https://example.com/rss" --count 10
Articles from a category
python scripts/freshrss.py category --name "Technology" --count 15
Starred articles
python scripts/freshrss.py starred --count 20
Search articles

Title only (fast, default 200 articles scanned, max 1000):

python scripts/freshrss.py search -k "keyword"

Title + content (slower, use --batch to control scan size):

python scripts/freshrss.py search -k "keyword" --deep --batch 500

Feed Management

List all subscriptions
python scripts/freshrss.py list-feeds
List categories
python scripts/freshrss.py list-categories
Unread counts
python scripts/freshrss.py unread-count
Add a feed
python scripts/freshrss.py add-feed --url "https://example.com/feed.xml" --category "News"
Move feed to another category
python scripts/freshrss.py move-feed --feed-id "feed/https://..." --to "NewCat" --from "OldCat"
Remove a feed
python scripts/freshrss.py remove-feed --feed-id "feed/https://..."
Mark article as read
python scripts/freshrss.py mark-read --item-id "tag:google.com,2005:reader/item/..."
Star an article
python scripts/freshrss.py star --item-id "tag:google.com,2005:reader/item/..."

Feed Recommendations

When asked for recommendations:

  1. Run list-feeds to see current subscriptions and categories
  2. Identify themes from feed titles and categories
  3. Use web search to find feeds in similar topics the user doesn't already follow
  4. Present recommendations grouped by interest area

Notes

  • Auth token is fetched fresh on each invocation (no caching needed)
  • All output is JSON for easy parsing
  • Search is client-side filtered since GReader API lacks native search
  • Feed stream IDs use format feed/https://example.com/rss
  • Use -v to include article summary in output (works on all reading commands)

Comments

Markdown supported