Copyright (c) 2025 Piethein Strengholt, piethein@strengholt-online.nl

RSSMonster is a modern, web-based RSS aggregator and reader inspired by Google Reader. It provides a lightweight, responsive interface for tracking and reading RSS feeds with built-in AI-powered search capabilities through the Model Context Protocol (MCP). Perfect for developers and power users who want full control over their RSS reading experience.

• Lightweight & Responsive: Built with Vue.js 3 and Express, styled with Bootstrap for a fluid experience across all devices
• Google Reader-inspired UX: Automatic mark-as-read on scroll and trending content identification
• Advanced Search Expressions: Powerful filtering with field operators (star:true, unread:false, clicked:true, tag:tech, title:javascript) and flexible date filters (@2025-12-14, @today, @yesterday, @"3 days ago", @"last Monday"). Combine multiple filters like title:javascript ai @today star:false sort:ASC for precise content discovery
• RSS Feed Generation: Create custom RSS feeds from your stored articles with flexible filtering by user, feed, category, starred status, and read/unread state. Perfect for sharing curated content or syncing with other applications (accessible via /rss endpoint with query parameters)
• Progressive Web App (PWA): Install on any device for native app-like experience with offline support
• Drag & Drop Management: Intuitive feed organization and categorization
• Dark Mode: Automatic theme switching
• OPML Support: Import and export feeds in OPML format for seamless migration
• Fever API Compatible: Works with popular RSS clients like Reeder (iOS)
• Google Reader API Compatible: Works with apps like News+, FeedMe, Reeder, and Vienna RSS
• Automated Actions: Define custom rules using regular expressions to automatically delete, star, mark as read, flag as advertisement, or mark articles as low quality
• Multi-user Support: Separate accounts with personalized feeds and preferences
• AI-Powered Assistant: Natural language search and feed management via Model Context Protocol (MCP)

• Node.js: Version 20.x or higher
• npm: Comes bundled with Node.js
• Git: For cloning the repository
• MySQL: Or any compatible database (with configuration adjustments)

git clone https://github.com/pietheinstrengholt/rssmonster.git
cd rssmonster

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install
cd ..

Copy the .env.example files to .env in both directories:

# Server configuration
cp server/.env.example server/.env

# Client configuration
cp client/.env.example client/.env

Edit server/.env:

DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password
DB_HOSTNAME=localhost
NODE_ENV=development

Edit client/.env:

VITE_APP_HOSTNAME=http://localhost:3000
VITE_NODE_ENV=development
VITE_ENABLE_AGENT=false  # Set to 'true' to enable AI assistant

Run database migrations and seed initial data:

cd server
./node_modules/.bin/sequelize db:migrate
./node_modules/.bin/sequelize db:seed:all

You can crawl feeds in two ways:

Option A: Manual crawl from command line

cd server
DISABLE_LISTENER=true npm run crawl

This runs a synchronous crawl of all active feeds and provides a summary upon completion.

Option B: Automated crawl via cron

Add a cron job to crawl feeds every 5 minutes by calling the API endpoint:

*/5 * * * * curl http://localhost:3000/api/crawl

Note: The API endpoint runs the crawl asynchronously in the background and returns immediately without output.

RSSMonster includes an AI-powered assistant that enables natural language interactions with your RSS feeds. Ask questions like:

• "Show me technology articles from the last week"
• "What are my favorite articles?"
• "Find unread posts about JavaScript"

To enable the AI assistant, configure the following environment variables:

Server (server/.env):

OPENAI_API_KEY=your-openai-api-key-here
OPENAI_MODEL_AGENT=gpt-5.1
OPENAI_MODEL_CRAWL=gpt-4o-mini

Client (client/.env):

VITE_ENABLE_AGENT=true

After configuration, restart both the client and server. The assistant provides:

• Natural language search across all articles
• Time-based filtering (e.g., "articles from last month")
• Article summarization, classification, and tagging
• Favorite and trending article discovery
• Smart recommendations based on reading habits

RSSMonster automatically tracks article clicks and uses AI to classify content with three quality metrics: advertisementScore (ad/promotional content detection), sentimentScore (emotional tone analysis), and qualityScore (content depth and accuracy assessment). These scores provide at-a-glance insights into article quality.

Note: All interactions are user-scoped, ensuring privacy and data isolation in multi-user environments.

Note for Developers: You can access the MCP server directly at /mcp for programmatic integration. Authentication requires a valid JWT token passed via the Authorization: Bearer <token> header. Obtain your token by authenticating through the /api/auth/login endpoint.

Client (with hot reload):

cd client
npm run dev

Server (with debugging):

cd server
npm run debug

The client will typically run on http://localhost:5173 and the server on http://localhost:3000.

1. Update Environment Variables

   Client (client/.env):

   VITE_APP_HOSTNAME=https://your-production-domain.com
   VITE_NODE_ENV=production

   Server (server/.env):

   NODE_ENV=production

2. Build the Client

   cd client
   npm run build

3. Move Static Files

   # Move the dist folder to the server directory
   mv client/dist server/

4. Start the Server

   cd server
   npm run start

# Build all images
docker-compose build

# Start containers
docker-compose up

• Client: http://localhost:8080
• Server API: http://localhost:3000
• MySQL: localhost:3306

Build the production image (combines server and optimized client):

docker build -t rssmonster .

Run the container with environment variables:

docker run -d \
  -e NODE_ENV=production \
  -e DB_HOSTNAME=your-db-host \
  -e DB_DATABASE=rssmonster \
  -e DB_USERNAME=rssmonster \
  -e DB_PASSWORD=your-secure-password \
  -p 3000:3000 \
  rssmonster

For production environments, use Let's Encrypt with Certbot for SSL/TLS certificates:

certbot certonly --standalone -d yourdomain.com --agree-tos -q

Create a weekly cron job:

# Example cron entry (runs weekly)
0 0 * * 0 certbot renew --quiet && cp /etc/letsencrypt/live/yourdomain.com/* /path/to/rssmonster/cert/

Add the following to your server/.env file:

ENABLE_HTTPS=true

The server will automatically use HTTPS with certificates from the cert/ directory. Ensure your SSL certificates are properly placed:

• cert/fullchain.pem
• cert/privkey.pem

Restart the server to apply the changes:

cd server
npm run start

Set up your AWS credentials: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html

Download and install: https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3.html

# Initialize EB application
eb init

# Create environment with MySQL database
eb create rssmonster-app \
  --envvars "NODE_ENV=production" \
  --database \
  --database.engine mysql \
  --database.username rssmonster \
  --database.password "your-secure-password"

# SSH into instance to run migrations
eb ssh rssmonster-app

# Run migrations inside the instance
/app/server/node_modules/.bin/sequelize db:migrate
/app/server/node_modules/.bin/sequelize db:seed:all

RSSMonster is compatible with the Fever API, enabling integration with third-party RSS clients.

• Fever API Endpoint: http://your-rssmonster-url/api/fever
• Authentication: Any valid RSSMonster username and password

• Reeder (iOS): Configure by adding a Fever account with the endpoint above

RSSMonster supports the Google Reader API, providing compatibility with a wide range of RSS clients.

• API Endpoint: http://your-rssmonster-url/api/greader
• Authentication: Use your RSSMonster username and password

# Login (returns SID and Auth tokens)
curl 'http://localhost:3000/api/greader/accounts/ClientLogin?Email=username&Passwd=password'

# Get subscriptions
curl -H "Authorization:GoogleLogin auth=username/token" \
  'http://localhost:3000/api/greader/reader/api/0/subscription/list?output=json'

# Get unread counts
curl -H "Authorization:GoogleLogin auth=username/token" \
  'http://localhost:3000/api/greader/reader/api/0/unread-count?output=json'

# Get articles
curl -H "Authorization:GoogleLogin auth=username/token" \
  'http://localhost:3000/api/greader/reader/api/0/stream/contents/reading-list'

• Authentication: ClientLogin with username/password
• Subscriptions: List, add, edit, remove feeds
• Tags/Categories: List, rename, delete categories
• Articles: Fetch by stream, feed, or category with pagination
• Mark as read/unread: Individual articles or mark all as read
• Star/unstar: Favorite articles
• Unread counts: Per feed, category, and total

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

RSSMonster is built with the following frameworks and libraries:

• Node.js - JavaScript runtime
• Express - Web framework
• Vue.js 3 - Frontend framework
• Bootstrap - UI framework
• Sequelize - ORM for database management
• feed-parser - RSS/Atom feed parsing

This project is licensed under the MIT License - see the LICENSE.md file for details.