airsstool

✨ 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

Related MCP server: RSS MCP Server

❓ 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

🚀 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

📚 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!