MCP RSS

MCP RSS is a Model Context Protocol (MCP) server for intelligent RSS feed management with advanced search capabilities, semantic search using AI embeddings, and a comprehensive reading workflow.

Features

• 📰 RSS Feed Management - Parse OPML files and automatically fetch articles from RSS feeds

• 🔍 Advanced Search - Keyword search with date range, category, and status filtering

• 🤖 Semantic Search - AI-powered natural language search using OpenAI embeddings (optional)

• 📊 Smart Organization - Four-status workflow (unread/read/favorite/archived)

• 📅 Daily Digest - Get today's unread articles grouped by category

• 🚀 High Performance - PostgreSQL with pgvector for efficient vector similarity search

• 🔄 Auto-Deduplication - Prevents duplicate articles and wasted API calls

• ⚡ Token-Efficient - Browse titles/excerpts first, fetch full content only when needed

• 📑 Pagination Support - Handle large feed collections (500+) with efficient pagination

Installation

Prerequisites

• Node.js (v18 or higher)

• Docker & Docker Compose (for PostgreSQL with pgvector)

• OpenAI API Key (optional, only for semantic search)

Quick Start with Docker Compose

1. Clone or install the package:

   npm install -g mcp_rss # OR for local development git clone <repository-url> cd mcp_rss npm install

2. Start PostgreSQL with pgvector:

   docker-compose up -d

3. Configure environment variables:

   cp .env.example .env # Edit .env with your settings

4. Build the project:

   npm run build

Database Setup

The project uses PostgreSQL 17 with pgvector extension for vector similarity search.

Using Docker Compose (Recommended):

Manual PostgreSQL Setup:

Configuration

Environment Variables

Create a .env file with the following configuration:

* Only required for semantic search feature. All other features work without it.

Claude Desktop Configuration

For local development, use the built dist folder:

For global installation via npm:

MCP Tools Reference

The server exposes 8 powerful tools for RSS feed management:

Token Efficiency Guide

All list/search tools now support ultra-efficient token usage:

• Default behavior: Returns ONLY titles and metadata (no excerpts, no content)

• Optional excerpts: Set includeExcerpt: true for content previews (moderate token usage)

• Full content: Set includeContent: true for complete article text (high token usage)

• On-demand content: Use get_article_full to fetch specific articles by ID (most efficient)

Recommended workflow (90%+ token savings):

1. Browse titles only with get_content or search_articles (default settings)

2. Identify interesting articles from titles alone

3. Optionally fetch excerpts for borderline cases with includeExcerpt: true

4. Fetch full content with get_article_full for selected articles only

Token Usage Comparison:

• Titles only: ~50-100 tokens per article

• Titles + excerpts: ~150-300 tokens per article

• Titles + full content: ~1,000-5,000 tokens per article

1. get_content

Get articles with basic filtering and pagination. Returns latest articles first (sorted by pubDate DESC).

Use this for:

• Browsing recent articles

• Checking unread articles

• Simple filtering by status or source

• Date range filtering for specific time periods

Token Efficiency:

• By default, returns ONLY titles and metadata (most token-efficient)

• Set includeExcerpt: true to add content previews

• Set includeContent: true to get full article text

• For best efficiency: browse titles only, then use get_article_full for specific articles

Parameters:

Example (titles only - most efficient):

Example (with date range and excerpts):

Example (favorite blogs with full content):

Response (default - titles only, no excerpt/content):

2. search_articles

Advanced search with keyword matching, date ranges, categories, and status filters. Searches both title and content.

Use this for:

• Finding articles on specific topics

• Date-based filtering

• Complex multi-criteria searches

• Category-specific searches

Parameters:

Example:

3. semantic_search

AI-powered semantic search using OpenAI embeddings. Finds conceptually similar articles even without exact keyword matches.

Use this for:

• Natural language queries

• Finding related concepts

• Research and discovery

• Topic exploration

Requirements:

• OPENAI_API_KEY must be set

• Only works for articles from 2020 onwards

• Automatically disabled if API key is missing (fails gracefully)

Parameters:

Example:

How it works:

1. Converts your query into a 1536-dimensional vector using OpenAI

2. Compares against article embeddings using pgvector cosine similarity

3. Returns semantically similar articles ranked by relevance

4. get_daily_digest

Get today's unread articles grouped by category. Perfect for daily reading workflows. Filters by publication date (pubDate), not fetch date.

Use this for:

• Morning briefings

• Daily catch-up

• Category-organized reading

• Articles published today (based on pubDate)

Parameters:

Example:

Response: Articles grouped by category, with up to N articles per category fetched today.

5. get_weekly_favorites

NEW: Get favorite articles from the last 7 days (titles only). Perfect for weekly review of bookmarked content.

Use this for:

• Weekly reading lists

• Reviewing saved articles from the past week

• Tracking important bookmarked content

• Quick overview of what you found valuable recently

Parameters: None

Example: No parameters needed - simply call the tool.

Response:

Features:

• Returns articles marked as "favorite" published in last 7 days

• Sorted by publication date (newest first)

• Ultra token-efficient - titles and metadata only

• No excerpts or content by default

• Use get_article_full to read full content of any article

6. get_article_full

Get full article content by ID. Use this for token-efficient reading: browse titles first, then fetch complete content only for articles you want to read.

Use this for:

• Reading full articles after browsing titles

• Getting complete content for specific interesting articles

• Token-efficient workflow (browse → select → read)

Parameters:

Example:

Response:

Token-Efficient Workflow:

7. get_sources

Get RSS feed sources with pagination and filtering. With hundreds of feeds, pagination is essential to avoid token limits.

Use this for:

• Discovering available sources

• Finding valid source names for filtering

• Exploring feed categories

• Browsing favorite blogs

Parameters:

Example (first page):

Example (favorites only):

Example (filter by category):

Response:

Pagination Example:

8. set_tag

Update article status to manage your reading workflow.

Use this for:

• Marking articles as read

• Saving favorites

• Archiving old articles

• Managing reading queue

Parameters:

Example:

Article Status Workflow

The server supports a comprehensive 4-status workflow:

Vector Search & Embeddings

How Embeddings Work

1. Automatic Generation: When fetching RSS articles, the server automatically generates embeddings for articles from 2020 onwards

2. OpenAI Integration: Uses text-embedding-3-small model (1536 dimensions)

3. Deduplication: Embeddings are only generated once per article (checked by URL)

4. Graceful Degradation: If OPENAI_API_KEY is missing or invalid, the server continues to work normally (embeddings skipped)

Storage

• Embeddings stored as vector(1536) in PostgreSQL using pgvector extension

• Enables fast cosine similarity search: ORDER BY embedding <=> query_vector

Cost Optimization

• Only articles from 2020+ get embeddings (configurable in RssService.shouldGenerateEmbedding())

• Duplicate articles are skipped (no redundant API calls)

• Embedding generation failures don't block article saving

Development

Project Structure

Building

Testing

Troubleshooting

Database Connection Issues

Error:

• Ensure PostgreSQL is running: docker-compose ps

• Check port 5433 is available: lsof -i :5433

• Verify environment variables match docker-compose settings

OpenAI API Errors

Error:

• Verify your API key at https://platform.openai.com/api-keys

• Ensure you have available credits

• Check the key isn't expired

Embeddings not being generated:

• Server works fine without API key (embeddings skipped)

• Check article dates (only 2020+ articles get embeddings)

• Look for errors in console logs

MCP Server Issues

Server not appearing in Claude Desktop:

1. Check Claude Desktop config path is correct

2. Verify dist/index.js exists (run npm run build)

3. Restart Claude Desktop after config changes

4. Check Claude Desktop logs for errors

Performance Tips

1. Adjust Update Interval: Set RSS_UPDATE_INTERVAL to 60+ minutes for production

2. Limit Embedding Generation: Embeddings are only for articles from 2020+

3. Use Pagination: Always use offset and limit for large result sets

4. Database Indexing: PostgreSQL automatically indexes the vector column

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript compiles without errors (npm run build)

• Environment variables are documented

• New features include appropriate error handling