RSS/Atom/JSON-Feed management tools for AI agents. Subscribe to feeds, fetch new articles, search content, manage read/star state, organize with categories a...
RSS/Atom/JSON-Feed management tools backed by a local SQLite database. All data operations are deterministic with zero LLM token cost — intelligence (filtering, ranking, summarization) belongs in your agent logic, not in these tools.
feeds_refresh to pull new items from all subscribed feeds.feeds_get_unread to get unread articles (titles, summaries, URLs, IDs).feeds_mark_read with ALL processed item IDs (interesting or not) so they aren't re-processed next cycle.Important: Always mark items as read after processing, even if they weren't interesting. Failing to do so causes items to accumulate and be re-evaluated every cycle.
| Tool | Purpose | Key params |
|---|---|---|
feeds_add | Subscribe to a new feed (auto-discovers from website URL) | url, category (optional) |
feeds_list | List all subscribed feeds | category (optional filter) |
feeds_info | Show details for a single feed | feed_id |
feeds_delete | Remove a feed subscription | feed_id |
feeds_refresh | Fetch new items from all feeds | — |
feeds_discover | Discover feed URLs from a website without subscribing | url |
feeds_retry | Reset error state and re-fetch a broken feed | feed_id |
| Tool | Purpose | Key params |
|---|---|---|
feeds_get_unread | Get unread items for digest processing | limit (default 50) |
feeds_get_items | Get items with flexible filtering | feed_id, unread_only, limit |
feeds_mark_read | Mark items as read after processing | item_ids (comma-separated) |
feeds_mark_all_read | Mark all items (or all in a feed) as read | feed_id (optional) |
items_mark_unread | Mark an item as unread | item_id |
items_search | Full-text search across item titles and content | query, feed_id (optional), limit |
items_star | Star/bookmark an item | item_id |
items_unstar | Remove star from an item | item_id |
items_starred | List all starred items | limit |
items_get_url | Get the URL for an item (for opening in browser) | item_id |
| Tool | Purpose | Key params |
|---|---|---|
items_tag | Add a user-defined tag to an item | item_id, tag |
items_by_tag | List all items with a given tag | tag, limit (optional) |
| Tool | Purpose | Key params |
|---|---|---|
categories_list | List all categories in use | — |
categories_create | Create a new category | name |
categories_set | Assign a category to a feed | feed_id, name |
| Tool | Purpose | Key params |
|---|---|---|
opml_import | Import feeds from an OPML file | file_path |
opml_export | Export all feeds to an OPML file | file_path |
| Tool | Purpose | Key params |
|---|---|---|
db_info | Show database stats (feed/item counts, DB size) | — |
# Auto-discovers feed URL from any website
feeds_add("https://blog.example.com")
# Direct feed URL with a category
feeds_add("https://example.com/feed.xml", category="tech")
# Discover feeds without subscribing
feeds_discover("https://example.com")
# 1. Refresh all feeds
feeds_refresh()
# 2. Get unread items
feeds_get_unread(limit=30)
# 3. After evaluating, mark ALL items as read
feeds_mark_read("42,43,44,45,46")
# Full-text search
items_search("machine learning", limit=10)
# Star interesting items for later
items_star(42)
# Review starred items
items_starred()
# Create a category
categories_create("tech")
# Move a feed to a category
categories_set(feed_id=1, name="tech")
# List feeds filtered by category
feeds_list(category="tech")
# Import feeds from another reader
opml_import("/path/to/subscriptions.opml")
# Export for backup
opml_export("/path/to/backup.opml")
# Tag an item for future reference
items_tag(42, "urgent")
items_tag(42, "ai-research")
# Find items with a specific tag
items_by_tag("ai-research")
feeds_get_unread output to keep token usage low. Full content is available via feeds_get_items if needed.feeds_add and it will find the RSS/Atom feed. Use direct feed URLs only if discovery fails.feedcli must be installed in the same Python environment as the agent:
pip install -e /path/to/feedcli
The database is stored at $XDG_DATA_HOME/feedcli/feedcli.db (default: ~/.local/share/feedcli/feedcli.db). No setup required — tables are created automatically on first use.
ZIP package — ready to use