rss-mcp-server

kiliczsh/rss-mcp-server

3.2

If you are the rightful owner of rss-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for parsing, analyzing, and monitoring RSS, Atom, and JSON feeds.

Tools
5
Resources
0
Prompts
0

RSS Feed MCP Server

A comprehensive Model Context Protocol (MCP) server for parsing, analyzing, and monitoring RSS, Atom, and JSON feeds. This server enables AI assistants to seamlessly interact with web feeds across the internet.

Features

🎯 Core Capabilities

  • Universal Feed Parsing: Supports RSS 2.0, RSS 1.0 (RDF), Atom, and JSON Feed formats
  • Advanced Search & Filtering: Search by keywords, author, category, or date range
  • Multi-Feed Comparison: Analyze and compare multiple feeds simultaneously
  • Feed Validation: Comprehensive structure validation with actionable recommendations
  • Flexible Output Formats: Both JSON (machine-readable) and Markdown (human-readable)
  • Remote & Local Support: Run as stdio, HTTP, or SSE transport

🛠️ Available Tools

1. rss_parse_feed

Parse and retrieve items from any RSS/Atom/JSON feed.

# Example: Parse a tech blog feed
{
  "url": "https://techcrunch.com/feed/",
  "limit": 20,
  "response_format": "markdown"
}

Use Cases:

  • Read latest blog posts
  • Monitor news updates
  • Extract structured feed content
  • Get quick feed overview
2. rss_search_feed

Search and filter feed items with advanced criteria.

# Example: Find Python articles published this month
{
  "url": "https://realpython.com/atom.xml",
  "keyword": "async",
  "category": "tutorials",
  "since_date": "2025-10-01",
  "limit": 10
}

Use Cases:

  • Find specific articles by topic
  • Filter by author or contributor
  • Get posts from specific categories
  • Search within content and titles
3. rss_compare_feeds

Compare multiple feeds side by side.

# Example: Compare tech news sources
{
  "urls": [
    "https://techcrunch.com/feed/",
    "https://www.theverge.com/rss/index.xml",
    "https://arstechnica.com/feed/"
  ],
  "response_format": "json"
}

Use Cases:

  • Compare posting frequency
  • Monitor multiple sources
  • Find common topics
  • Unified view of updates
4. rss_validate_feed

Validate feed structure and get improvement recommendations.

# Example: Validate your blog feed
{
  "url": "https://myblog.com/feed.xml"
}

Use Cases:

  • Verify feed compliance
  • Troubleshoot parsing issues
  • Get quality recommendations
  • Pre-submission validation
5. rss_get_feed_metadata

Extract feed metadata without parsing all items (lightweight).

# Example: Quick feed info check
{
  "url": "https://example.com/rss",
  "response_format": "json"
}

Use Cases:

  • Quick feed information
  • Verify feed availability
  • Get title and description
  • Monitor feed status

📚 Available Resources

Resources provide pre-configured RSS feed collections through OPML files, making it easy to access common feeds without manually entering URLs.

feeds://list

List all available RSS feeds from your OPML configuration.

Returns: JSON containing all feeds with metadata (name, title, xmlUrl, htmlUrl, category, type)

Use Cases:

  • Browse available feeds
  • Get feed URLs programmatically
  • Explore feed categories
  • Build feed selectors
feeds://categories

List all feed categories with statistics.

Returns: JSON containing categories with feed counts and feed lists per category

Use Cases:

  • Organize feeds by topic
  • Filter feeds by category
  • Get category statistics
  • Build category navigation

🗂️ OPML Feed Management

The server uses OPML files to manage feed collections:

Default Feeds: The server includes 14 curated feeds across categories:

  • Tech News (Hacker News, TechCrunch, The Verge, Ars Technica)
  • Developer (GitHub Blog, Dev.to, CSS-Tricks)
  • AI & ML (OpenAI, Anthropic, Hugging Face)
  • Python (Python Insider, Real Python)
  • General News (BBC Technology, Reuters Technology)

Custom Feeds: Create your own feed collection:

  1. Create directory: mkdir -p ~/.rss-mcp/
  2. Add your OPML file: ~/.rss-mcp/feeds.opml
  3. Restart the server

OPML Format Example:

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
  <head>
    <title>My RSS Feeds</title>
  </head>
  <body>
    <outline text="Tech News" title="Tech News">
      <outline
        text="Hacker News"
        title="Hacker News"
        type="rss"
        xmlUrl="https://hnrss.org/frontpage"
        htmlUrl="https://news.ycombinator.com/"/>
    </outline>
  </body>
</opml>

Installation

Prerequisites

  • Python 3.10 or higher
  • UV (Python package manager)

Setup

  1. Install UV (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Clone the repository:
git clone https://github.com/kiliczsh/rss-mcp-server.git
cd rss-mcp-server
  1. Install dependencies:
uv sync
  1. Verify installation:
uv run server.py --help

Usage

Stdio Transport (Default - for Claude Desktop)

The default stdio transport is perfect for integration with Claude Desktop and other MCP clients:

uv run server.py

Claude Desktop Configuration:

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rss": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/rss-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

HTTP Transport (Remote Access)

For remote access or web service integration:

uv run server.py --transport http --port 8000

Access at: http://localhost:8000

SSE Transport (Real-time Updates)

For server-sent events and real-time communication:

uv run server.py --transport sse --port 8000

Examples

Example 1: Read Latest Tech News

# Parse TechCrunch feed
{
  "tool": "rss_parse_feed",
  "params": {
    "url": "https://techcrunch.com/feed/",
    "limit": 10,
    "response_format": "markdown"
  }
}

Example 2: Find AI Research Articles

# Search for AI-related posts
{
  "tool": "rss_search_feed",
  "params": {
    "url": "https://arxiv.org/rss/cs.AI",
    "keyword": "transformer",
    "since_date": "2025-10-01",
    "limit": 5
  }
}

Example 3: Compare News Sources

# Compare multiple tech news feeds
{
  "tool": "rss_compare_feeds",
  "params": {
    "urls": [
      "https://news.ycombinator.com/rss",
      "https://www.reddit.com/r/programming/.rss",
      "https://techcrunch.com/feed/"
    ]
  }
}

Example 4: Validate Your Feed

# Check if your blog feed is properly formatted
{
  "tool": "rss_validate_feed",
  "params": {
    "url": "https://myblog.com/feed.xml"
  }
}

Architecture

Design Principles

Following MCP best practices, this server is built with:

  • Agent-Centric Design: Tools are designed for complete workflows, not just API wrappers
  • Context Optimization: Responses are concise with optional detail levels
  • Actionable Errors: Error messages guide users toward correct usage
  • Natural Task Subdivision: Tool names reflect how humans think about tasks
  • Composable Code: Shared utilities avoid duplication

Core Components

server.py
├── HTTP Client Management (lifespan)
├── Feed Parsers (RSS/Atom/JSON)
├── Helper Functions
│   ├── fetch_url()
│   ├── detect_feed_type()
│   ├── parse_rss_feed()
│   ├── parse_atom_feed()
│   ├── parse_json_feed()
│   ├── format_feed_markdown()
│   ├── filter_items()
│   └── truncate_response()
└── MCP Tools
    ├── rss_parse_feed
    ├── rss_search_feed
    ├── rss_compare_feeds
    ├── rss_validate_feed
    └── rss_get_feed_metadata

Response Formats

Markdown (Default):

  • Human-readable formatting
  • Clean headers and lists
  • Truncated content previews
  • Best for user-facing output

JSON:

  • Complete structured data
  • All available fields
  • Machine-parseable
  • Best for programmatic processing

Supported Feed Formats

RSS 2.0

Most common format, widely supported across blogs and news sites.

Key Elements:

  • <channel>: Feed metadata
  • <item>: Individual entries
  • <title>, <link>, <description>: Core fields
  • <pubDate>: Publication date
  • <category>: Topic classification

RSS 1.0 (RDF)

RDF-based format with better namespace support.

Key Elements:

  • Uses RDF/XML structure
  • Dublin Core metadata
  • Better extensibility

Atom

Modern standard with strict requirements and better date handling.

Key Elements:

  • <feed>: Feed container
  • <entry>: Individual entries
  • <id>: Required unique identifier
  • <updated>: Required timestamp
  • <content>: Full content with type attribute

JSON Feed

JSON-based alternative to XML formats.

Key Elements:

  • version: Format version
  • items: Array of entries
  • content_html / content_text: Content variants
  • date_published, date_modified: Timestamps

Error Handling

The server provides clear, actionable error messages:

HTTP Errors

HTTP error 404 when fetching https://example.com/feed.xml.
Please verify the URL is correct and accessible.

Network Errors

Network error when fetching https://example.com/feed.xml: Connection timeout.
Please check your internet connection and try again.

Parse Errors

Invalid XML format: mismatched tag at line 42.
The feed may be malformed. Try using rss_validate_feed for details.

Performance & Limits

  • Character Limit: Responses truncated at 25,000 characters
  • Item Limit: Maximum 100 items per request
  • Concurrent Feeds: Up to 5 feeds in comparison
  • Request Timeout: 30 seconds per feed fetch
  • HTTP Client: Persistent connection with keep-alive

Troubleshooting

Issue: Feed not parsing

Solution:

  1. Verify URL is accessible in browser
  2. Check feed format with rss_validate_feed
  3. Ensure URL uses http:// or https://

Issue: Empty results

Solution:

  1. Check if feed contains items
  2. Verify filters aren't too restrictive
  3. Try without filters first

Issue: Truncated responses

Solution:

  1. Use limit parameter to reduce items
  2. Apply filters to narrow results
  3. Use JSON format for programmatic processing

Contributing

This server follows MCP best practices:

  1. Tool Design: Focus on workflows, not just API endpoints
  2. Documentation: Comprehensive docstrings with examples
  3. Error Messages: Actionable guidance for users
  4. Code Quality: DRY principle, composable functions
  5. Type Safety: Full Pydantic validation

Technical Details

Dependencies

  • mcp: FastMCP framework for MCP server implementation
  • httpx: Async HTTP client for feed fetching
  • pydantic: Input validation and type safety

Type Safety

All inputs validated with Pydantic models:

  • URL format validation
  • Parameter constraint checking
  • Enum-based format selection
  • Automatic whitespace stripping

Async Architecture

  • Non-blocking I/O for all network operations
  • Concurrent feed fetching in comparisons
  • Proper async context managers
  • Lifespan management for HTTP client

Documentation

📚 Comprehensive guides available in the docs/ folder:

  • - Quick start guide with UV setup
  • - 5-minute guide with examples
  • - 20+ practical usage examples
  • - Production deployment guide
  • - Development workflow and code quality
  • - Complete logging documentation
  • - Project change history
  • - Complete project overview

License

MIT License - see file for details

Credits

Built following MCP best practices and the mcp-builder skill guidelines.

Support

For issues, questions, or contributions:

Made with ❤️ for the MCP ecosystem