airsstool
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.
✨ Features
- 🤖 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
❓ Why airsstool?
The RSS Advantage
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
When to Use airsstool
| 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 |
🚀 Quick Start
📋 Prerequisites
- Python 3.10+
- A running RSSHub instance
📦 Installation
pip install airsstool
If you are on macOS and have Homebrew installed, you can also install via pipx (recommended for easier CLI access):
brew install pipx
pipx install airsstool
⚙️ Configuration
Set environment variables for your RSSHub instance:
export RSSHUB_URL="http://your-rsshub-instance:1200"
Default is https://rsshub.app.
🗄️ Initialize Database
After installation, initialize the database:
airsstool init
This 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 --force
Note: 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.
📖 Usage
💻 CLI Tool
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_news
🔌 MCP Server
Run the MCP server:
airsstool-mcp
Or 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"
}
}
}
}
🛠️ Available MCP Tools
| 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 |
📚 CLI Commands Reference
📋 List Commands
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 users
📥 Fetch Commands
airsstool 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)
📰 Subscription Commands
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 PATH
🤖 For OpenClaw Users
The companion skill is available on ClawHub as Site Feeds. Install it with:
clawhub install site-feeds
The skill enables OpenClaw agents to fetch updates and content from websites using airsstool.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
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!
Metadata
Release files for airsstool 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| airsstool-1.0.2.tar.gz | 36.4 kB | With provenance | Details for airsstool-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| airsstool-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for airsstool-1.0.2-py3-none-any.whl |
Total release size: 75.1 kB
Release files / airsstool-1.0.2.tar.gz
| Download URL | airsstool-1.0.2.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64656ffb591931575a089ab2269ae18afb8d76a30e97d62be9cf36070ee0e73d
|
|
BLAKE2b-256 checksum How to use checksums |
dbc289c6c355a175636f8f1559ad71df422b5e7d425bdaa1298b7d977eece732
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logRelease files / airsstool-1.0.2-py3-none-any.whl
| Download URL | airsstool-1.0.2-py3-none-any.whl |
|---|---|
| Size | 38.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b3d43d09883b421b4652fd590e9be4eef05ed6f28ea7b1f8eca76857d118e2e
|
|
BLAKE2b-256 checksum How to use checksums |
53a9e40ccd3a5f767e4f09dd41e50c1e18b7337ef7410ec9b6150f1b25581696
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logSecurity for airsstool 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for airsstool-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.