Skip to main content
airsstool logo

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 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.

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)

Source distribution for airsstool 1.0.2
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)

Table of built distributions (wheels) for airsstool 1.0.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page