Give your AI agent the ability to efficiently browse the web and fetch RSS feeds.
Please give this repo a πstar if you find it helpful
A RSSHub CLI tool and MCP server that enables AI agents to discover and fetch RSS feeds from 1500+ websites - GitHub trending, YouTube channels, Reddit threads, news sites, and more.
- π€ MCP Server: Expose RSSHub capabilities as MCP tools for AI agents
- π» CLI Tool: Command-line interface for manual RSS feed management
- π Subscription Management: Organize RSS feeds into subscription groups
- π Multiple Output Formats: Markdown (default, agent-friendly & token-efficient), plus all formats natively supported by RSSHub (RSS, Atom, JSON Feed, and RSS3)
- π Content Filtering: Leverage RSSHub's native filtering (title, description, author, category, time)
- π RSSHub Routes Database: Built-in database of 3000+ RSSHub routes
While browser automation tools (like Playwright, Puppeteer) can render and extract content from any website, they come with overhead: launching a browser instance, waiting for page loads, and parsing complex HTML. For real-time content fetching, this can be overkill.
RSS (Really Simple Syndication) offers a lightweight alternative - it's a standardized format for distributing content, like a "news feed" that websites publish. RSSHub extends this to 1500+ websites that don't natively offer RSS, parsing and standardizing their content.
airsstool bridges RSSHub with AI agents by providing:
- Lightweight & fast - No browser needed, just HTTP requests to structured feeds
- Token-efficient Markdown - Clean, structured output by default (vs verbose HTML)
- One consistent API - Same interface for YouTube, GitHub, Instagram, news sites, etc.
- Built-in filtering - Leverage RSSHub's native filtering by keywords, time, authors
- Reliable structure - RSS feeds have consistent schema, no need for site-specific parsers
| Use Case | Example Questions | Works? |
|---|---|---|
| Real-time news tracking | "What's the latest on the election?" "Any updates on the earthquake?" |
β Perfect for live events |
| Content monitoring | "Any new posts from MrBeast?" "Show me today's GitHub trending" |
β Ideal for scheduled checks |
| Topic filtering | "Find AI news from Hacker News" "Bitcoin price updates" |
β Great with filters |
| Multi-source aggregation | "Get updates from all my subscriptions" | β Built for this |
| Historical research | "What happened in 2020?" "Compare news from last year" |
β Use web search instead |
| Deep content analysis | "Summarize this specific article" "Extract data from this page" |
β Use browser tools instead |
| Interactive websites | "Book a flight" "Fill out this form" |
β Not designed for this |
- Python 3.10+
- A running RSSHub instance
pip install airsstoolIf you are on macOS and have Homebrew installed, you can also install via pipx (recommended for easier CLI access):
brew install pipx
pipx install airsstoolSet environment variables for your RSSHub instance:
export RSSHUB_URL="http://your-rsshub-instance:1200"Default is https://rsshub.app.
After installation, initialize the database:
airsstool initThis will automatically download routes data from your RSSHub instance ($RSSHUB_URL/api/namespace) and create the database at ~/.airsstool/airsstoolDB.db (or %USERPROFILE%\.airsstool\airsstoolDB.db on Windows).
Options:
--db-path PATH- Custom database location--force- Force recreate (deletes existing database)
# Custom database path
airsstool init --db-path /custom/path/airsstoolDB.db
# Force recreate
airsstool init --forceNote: Routes data is automatically downloaded from your RSSHub instance during
init. If the download fails, you can manually place arsshub-routes.jsonfile in~/.airsstool/before runninginit. The JSON format should match RSSHub's official routes documentation.
After installing and initializing, you can use the airsstool command directly:
# Initialize database (first time only)
airsstool init
# List all RSS categories
airsstool list categories
# List websites (with optional filters)
airsstool list websites
airsstool list websites --category programming --page-size 10
# List routes for a website
airsstool list routes youtube
# Check route details
airsstool check youtube user
# Fetch RSS content
airsstool fetch /github/trending/daily/javascript/en
airsstool fetch /youtube/user/@MrBeast --limit 5
airsstool fetch /hackernews/best --format rss --limit 10
airsstool fetch /instagram/user/instagram --brief 100
# Subscription management
airsstool add-subscription --user alice --subscription tech_news
airsstool subscribe --user alice --subscription tech_news --path /github/trending/daily/any/en --description "GitHub Trending"
airsstool fetch --user alice --subscription tech_newsRun the MCP server:
airsstool-mcpOr if using with Claude Code or other MCP clients, add to your MCP configuration:
{
"mcpServers": {
"airsstool": {
"command": "airsstool-mcp",
"env": {
"RSSHUB_URL": "http://your-rsshub-instance:1200"
}
}
}
}| Tool | Description |
|---|---|
list_rss_categories |
List all RSS categories |
list_rss_websites |
List websites with pagination and filtering |
list_rss_routes |
List routes for a website (fuzzy search supported) |
check_rss_route_detail |
Get detailed info about a route |
list_users |
List all users |
list_rss_subscription |
List user's subscription groups |
list_rss_subscribed_paths |
List paths in a subscription |
add_rss_subscription |
Create a new subscription group |
subscribe_rss_path |
Add a path to subscription |
unsubscribe_rss_subscription |
Delete a subscription group and all its paths |
remove_rss_path |
Remove a specific path from subscription |
fetch_rss |
Fetch and parse RSS content |
fetch_rss_subscription |
Fetch all paths in a subscription |
airsstool list categories # List all categories
airsstool list websites [--category CAT] [--page-size N] [--page-num N] [--enable-nsfw]
airsstool list routes <website> # List routes for a website
airsstool list subscriptions --user USER # List user's subscriptions
airsstool list paths --user USER --subscription NAME
airsstool list users # List all usersairsstool fetch <path> [options]
airsstool fetch --user USER --subscription NAME [options]
Options:
--limit N Limit number of feeds
--offset N Skip first N feeds
--format FORMAT Output format: markdown (default), rss, atom, json, rss3
--brief N Output brief text (>=100 chars)
--filter PATTERN Filter title and description
--filter-title PATTERN Filter title only
--filter-time SECONDS Filter by time range
--filterout PATTERN Exclude matching content
--enable-nsfw Include NSFW content (for list websites)airsstool add-subscription --user USER --subscription NAME
airsstool subscribe --user USER --subscription NAME --path PATH --description DESC [--force]
airsstool unsubscribe --user USER --subscription NAME
airsstool remove-subscription --user USER --subscription NAME --path PATHThe companion skill is available on ClawHub as Site Feeds. Install it with:
clawhub install site-feedsThe skill enables OpenClaw agents to fetch updates and content from websites using airsstool.
This project is licensed under the MIT License - see the LICENSE file for details.
This project is built on top of RSSHub, an amazing open-source RSS hub.
- RSSHub Code: https://github.com/DIYgod/RSSHub
- RSSHub Docs: https://docs.rsshub.app/
If you find airsstool useful, please consider starring both this project and RSSHub!