airsstool

<div align="center"> <img src="assets/airsstool_logo.png" alt="airsstool logo" width="150"> <h1>airsstool</h1> <p>Bridging your AI agent with RSSHub for efficient real-time content fetching from 1500+ websites</p> <p>Please give this repo a 🌟star if you find it helpful</p> </div>

<p align="center"> <a href="README_zh.md">中文</a> </p>

---

<p align="center"> <i>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.</i> </p>

✨ 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?"<br>"Any updates on the earthquake?"	✅ Perfect for live events
Content monitoring	"Any new posts from MrBeast?"<br>"Show me today's GitHub trending"	✅ Ideal for scheduled checks
Topic filtering	"Find AI news from Hacker News"<br>"Bitcoin price updates"	✅ Great with filters
Multi-source aggregation	"Get updates from all my subscriptions"	✅ Built for this
Historical research	"What happened in 2020?"<br>"Compare news from last year"	❌ Use web search instead
Deep content analysis	"Summarize this specific article"<br>"Extract data from this page"	❌ Use browser tools instead
Interactive websites	"Book a flight"<br>"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 a rsshub-routes.json file in ~/.airsstool/ before running init. 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!