feed-mcp

MCP Server for RSS, Atom, and JSON Feeds

Quick Start Examples

Here are some practical configurations for Claude Desktop that demonstrate common use cases:

{
  "mcpServers": {
    "feed-tech-news": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://techcrunch.com/feed/",
        "https://feeds.arstechnica.com/arstechnica/index",
        "https://www.theverge.com/rss/index.xml",
        "https://www.wired.com/feed/rss",
        "https://www.engadget.com/rss.xml"
      ]
    },
    "feed-security": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://krebsonsecurity.com/feed/",
        "https://www.schneier.com/blog/atom.xml",
        "https://thehackernews.com/feeds/posts/default",
        "https://www.bleepingcomputer.com/feed/"
      ]
    },
    "feed-webdev": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://css-tricks.com/feed/",
        "https://www.smashingmagazine.com/feed/",
        "https://mozilla.hacks.org/feed/"
      ]
    }
  }
}

Add any of these configurations to your Claude Desktop to instantly access the latest news and articles from your chosen topics.

OPML Support

feed-mcp supports loading feed URLs from OPML (Outline Processor Markup Language) files, making it easy to import subscription lists from RSS readers like Feedly, Inoreader, or any other feed aggregator.

Using OPML Files

Instead of specifying individual feed URLs, you can use an OPML file:

# Load from local OPML file
go run main.go run --opml feeds.opml

# Load from remote OPML URL
go run main.go run --opml https://example.com/my-feeds.opml

Docker with OPML

You can also use OPML files with Docker:

{
  "mcpServers": {
    "feed-from-opml": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/feeds.opml:/feeds.opml:ro",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run", "--opml", "/feeds.opml"
      ]
    }
  }
}

OPML Format Support

feed-mcp supports standard OPML 2.0 format with nested categories:

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
    <head>
        <title>My Feed Subscriptions</title>
    </head>
    <body>
        <outline text="Technology">
            <outline text="TechCrunch" xmlUrl="https://techcrunch.com/feed/" />
            <outline text="The Verge" xmlUrl="https://www.theverge.com/rss/index.xml" />
        </outline>
        <outline text="Security">
            <outline text="Krebs on Security" xmlUrl="https://krebsonsecurity.com/feed/" />
        </outline>
    </body>
</opml>

Key Features

Backwards Compatible: Existing feed URL usage continues to work unchanged
Flexible Input: Supports both local files and remote URLs
Nested Categories: Handles OPML files with folder structures from feed readers
Security: Same URL validation and security features apply to OPML-loaded feeds
Error Handling: Clear error messages for invalid OPML files or network issues

Exporting from Popular Feed Readers

Most RSS readers support OPML export:

Feedly: Settings → OPML → Export
Inoreader: Preferences → Folders and Tags → Export OPML
NewsBlur: Account → Import/Export → Export Stories
The Old Reader: Settings → Import/Export → Export

Simply export your subscriptions and use the resulting OPML file with feed-mcp!

Dynamic Feed Management (Phase 1)

feed-mcp now supports runtime feed management, allowing you to add, remove, and manage feeds dynamically without restarting the server. This feature is perfect for building feed aggregators, content management systems, or any application that needs flexible feed handling.

Enabling Dynamic Feed Management

To enable runtime feed management, use the --allow-runtime-feeds flag:

# Start with dynamic feed management enabled
go run main.go run --allow-runtime-feeds

# Or with Docker
docker run -i --rm ghcr.io/richardwooding/feed-mcp:latest run --allow-runtime-feeds

When enabled, the server starts without requiring initial feeds and provides additional MCP tools for feed management.

Available Management Tools

`add_feed` - Add New Feeds at Runtime

Add RSS, Atom, or JSON feeds dynamically:

{
  "tool": "add_feed",
  "arguments": {
    "url": "https://techcrunch.com/feed/",
    "title": "TechCrunch",
    "category": "Technology", 
    "description": "Latest technology news"
  }
}

Parameters:

url (required): RSS/Atom/JSON feed URL
title (optional): Human-readable feed title
category (optional): Category for organization
description (optional): Feed description

Response: Returns feed metadata including auto-generated feed ID, validation status, and item count.

`remove_feed` - Remove Feeds by ID or URL

Remove feeds using either feed ID or URL:

{
  "tool": "remove_feed",
  "arguments": {
    "feedId": "abc123"
  }
}

Or remove by URL:

{
  "tool": "remove_feed", 
  "arguments": {
    "url": "https://techcrunch.com/feed/"
  }
}

Response: Returns information about the removed feed including items count.

`list_managed_feeds` - View All Feeds with Metadata

Get comprehensive information about all managed feeds:

{
  "tool": "list_managed_feeds",
  "arguments": {}
}

Response includes:

Feed ID, URL, title, category, description
Status (active, error, paused)
Source (startup, opml, runtime)
Last fetched timestamp and error details
Current item count
Addition timestamp

Feed Sources and Metadata

The system tracks different feed sources:

startup - Feeds provided via command line arguments
opml - Feeds loaded from OPML files
runtime - Feeds added dynamically via add_feed tool

Feed Status Tracking

Each feed maintains status information:

active - Feed is working normally
error - Feed has fetch errors (with error details)
paused - Feed temporarily disabled (Phase 2 feature)

Integration Examples

Claude Desktop Configuration

{
  "mcpServers": {
    "dynamic-feeds": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest", 
        "run", "--allow-runtime-feeds"
      ]
    }
  }
}

Building a Feed Aggregator

# Start dynamic server
feed-mcp run --allow-runtime-feeds

# Add feeds programmatically
curl -X POST /mcp/tools/add_feed \
  -d '{"url": "https://example.com/feed.xml", "category": "news"}'

# List all managed feeds
curl -X POST /mcp/tools/list_managed_feeds

Security and Validation

All runtime feeds go through the same URL validation as startup feeds
Private IP blocking and SSRF protection apply to dynamically added feeds
Malicious or invalid URLs are rejected with clear error messages
Only runtime-added feeds can be removed (startup/OPML feeds are protected)

Performance Characteristics

Feed Addition: ~50-100ms including validation and initial fetch
Feed Removal: ~10-20ms with cache cleanup
Feed Listing: ~1-5ms for metadata retrieval
Memory Impact: ~25KB per additional feed
Concurrency: Thread-safe operations with minimal locking

Phase 2 Roadmap

Upcoming features in development:

Feed pause/resume functionality for temporary feed management
Batch operations for adding/removing multiple feeds
Feed update metadata for modifying titles, categories, descriptions
Refresh individual feeds on-demand
Feed statistics and analytics with detailed metrics
Persistent storage for feed configurations
REST API for external integrations

Limitations (Phase 1)

Feeds are stored in memory only (lost on restart)
Cannot modify startup or OPML feeds at runtime
No persistent configuration storage
Limited to basic metadata (title, category, description)

MCP Prompts Support (Phase 2)

feed-mcp includes comprehensive MCP Prompts support that enables AI assistants to analyze feed data with intelligent, contextual prompts. These prompts provide deep insights into content trends, patterns, and feed performance.

Available Intelligence Prompts

`analyze_feed_trends` - Content Trend Analysis

Analyze patterns and trends across multiple feeds over time:

Parameters:

timeframe (optional): Time period to analyze (e.g., '24h', '7d', '30d') - defaults to '24h'
categories (optional): Comma-separated list of categories to filter by

Example Usage:

Analyze feed trends for the past week focusing on technology categories

Insights Generated:

Publication frequency patterns and peak activity times
Topic distribution and content themes
Source activity levels and error rates
Content pattern analysis and recommendations

`summarize_feeds` - Comprehensive Feed Summaries

Generate detailed summaries of feed content with key insights:

Parameters:

feed_ids (optional): Comma-separated list of specific feed IDs - defaults to all feeds
summary_type (optional): Type of summary ('brief', 'detailed', 'executive') - defaults to 'brief'

Example Usage:

Generate a detailed summary of all technology feeds

Summary Types:

Brief: Quick overview with key metrics and status
Detailed: Complete breakdown by feed with individual analysis
Executive: Strategic overview with recommendations and key insights

`monitor_keywords` - Intelligent Keyword Tracking

Track specific keywords or topics across all feeds with alerts:

Parameters:

keywords (required): Comma-separated list of keywords or phrases to monitor
timeframe (optional): Time period to monitor - defaults to '24h'
alert_threshold (optional): Minimum mentions to trigger alert - defaults to 1

Example Usage:

Monitor keywords "artificial intelligence, machine learning, AI" for alerts

Features:

Cross-feed keyword tracking with source breakdown
Smart alert system with configurable thresholds
Trend analysis and mention frequency tracking
Contextual recommendations for keyword monitoring

`compare_sources` - Multi-Source Analysis

Compare coverage and perspectives across different feed sources:

Parameters:

topic (required): Topic or keyword to compare across sources
feed_ids (optional): Specific feeds to compare - defaults to all feeds

Example Usage:

Compare how different sources cover "climate change"

Analysis Includes:

Coverage depth comparison across sources
Unique perspectives and angles from each source
Content gap analysis and recommendations
Source reliability and consistency metrics

`generate_feed_report` - Detailed Performance Reports

Generate comprehensive reports on feed performance and analytics:

Parameters:

report_type (optional): Report type ('performance', 'content', 'engagement', 'comprehensive') - defaults to 'comprehensive'
timeframe (optional): Report time period (e.g., '7d', '30d', '90d') - defaults to '7d'

Example Usage:

Generate a comprehensive feed performance report for the past month

Report Types:

Performance: System health, uptime, error rates, response times
Content: Volume metrics, quality analysis, topic coverage
Engagement: Usage patterns, popular content, access analytics
Comprehensive: Complete overview with all metrics and strategic recommendations

Technical Implementation

The MCP Prompts system is built with:

Intelligent Analysis: Uses advanced algorithms for trend detection and pattern recognition
Flexible Timeframes: Supports human-friendly time formats ('24h', '7d', '1m', etc.)
Smart Validation: Comprehensive parameter validation with helpful error messages
Consistent Results: Uses non-cryptographic hash functions (hash/fnv) for reproducible demo data
Performance Optimized: Efficient data processing with minimal resource usage
Extensible Design: Easy to add new prompts and analysis capabilities

Integration with Claude Desktop

All prompts are automatically available in Claude Desktop when you configure feed-mcp:

{
  "mcpServers": {
    "feed-intelligence": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://techcrunch.com/feed/",
        "https://www.theverge.com/rss/index.xml",
        "https://feeds.arstechnica.com/arstechnica/index"
      ]
    }
  }
}

Once configured, you can use natural language to invoke any prompt:

"Analyze trends in my tech feeds for the past week"
"Generate an executive summary of all feeds"
"Monitor mentions of 'artificial intelligence' with alerts"
"Compare how different sources cover 'quantum computing'"
"Create a comprehensive performance report"

Advanced Use Cases

Content Strategy Planning

Generate a comprehensive report focusing on content analysis for the past month,
then analyze trends to identify emerging topics for content planning

Competitive Intelligence

Compare sources covering "electric vehicles" and monitor keywords 
"Tesla, Ford, GM" with alerts for trending mentions

Editorial Analytics

Analyze feed trends for technology category, then generate a detailed 
summary of top-performing content types and publication patterns

Future Enhancements (Phase 3)

Planned intelligent features:

Custom Prompt Templates: Create reusable prompt configurations
Automated Insights: Scheduled analysis with proactive alerts
Machine Learning Integration: Advanced pattern recognition and prediction
Cross-Feed Correlation: Identify relationships between different feed sources
Sentiment Analysis: Track emotional tone and sentiment trends
Export Capabilities: Generate reports in various formats (PDF, CSV, JSON)

Features

Serves RSS, Atom, and JSON feeds via the MCP protocol
MCP Prompts Support (Phase 2) for intelligent feed analysis and content insights
Dynamic Feed Management (Phase 1) for runtime feed addition, removal, and management
OPML support for importing feed subscriptions from RSS readers (Feedly, Inoreader, etc.)
MCP Resources support with dynamic feed discovery and real-time subscriptions
MCP Tools support for direct feed operations (legacy compatibility)
Supports Docker and Podman for easy deployment
CLI installable via go install
Compatible with Claude Desktop as an MCP server
Caching for efficient feed retrieval
Built-in rate limiting (2 req/s default) to be respectful to feed servers
Circuit breaker pattern for fault tolerance against failing feeds
HTTP connection pooling for improved performance with multiple feeds
Retry mechanism with exponential backoff and jitter for handling transient failures
URL validation and sanitization to prevent SSRF attacks and security vulnerabilities
Private IP and localhost blocking (configurable) for enhanced security
Graceful shutdown with signal handling (SIGINT/SIGTERM)
Supports multiple feeds simultaneously
Extensible and configurable

Architecture

The core of feed-mcp is a Go server that fetches, parses, and serves RSS/Atom/JSON feeds over the MCP protocol. The main architectural components are:

Command-line Interface (CLI): Uses kong for parsing commands and flags. The run command is the entry point for starting the server.
Feed Fetching & Parsing: Feeds are fetched and parsed using gofeed. The server supports multiple feeds, which are periodically refreshed and cached.
Caching Layer: Feed data is cached using gocache and ristretto for efficient retrieval and reduced network usage.
Rate Limiting: Built-in HTTP rate limiting using golang.org/x/time/rate prevents overwhelming feed servers with requests.
Circuit Breaker: Implements circuit breaker pattern using sony/gobreaker to temporarily stop fetching from consistently failing feeds, with configurable failure thresholds and recovery timeouts.
HTTP Connection Pooling: Optimized HTTP connection pooling with configurable pool sizes and timeouts for improved performance when fetching multiple feeds simultaneously.
Retry Mechanism: Automatic retry with exponential backoff and jitter for handling transient network failures, DNS errors, and server errors (5xx), while avoiding retries for client errors (4xx).
MCP Protocol Server: Implements the MCP protocol using the official MCP Go SDK, allowing integration with clients like Claude Desktop.
Transport Options: Supports different transports (e.g., stdio, HTTP with SSE) for communication with MCP clients.
Graceful Shutdown: Handles SIGINT and SIGTERM signals for clean termination, with configurable shutdown timeout (default 30s).
Docker/Podman Support: The server can be run in containers for easy deployment and integration.

How it Works

Startup: The CLI parses arguments and starts the server with the specified feeds and transport.
Feed Management: The server fetches and parses the configured feeds, storing results in the cache.
Serving Requests: When an MCP client connects, the server responds to requests for feed data using the cached content, updating as needed.
Graceful Shutdown: When receiving shutdown signals, the server cleanly terminates all operations and exits.
Extensibility: The architecture allows for adding new transports, feed sources, or output formats with minimal changes.

For contributors:

The main entry point is main.go, which wires up the CLI and server.
Feed logic is in the model and store packages.
MCP protocol handling is in the mcpserver package.
Tests are provided for core logic; see *_test.go files for examples.

MCP Resources Support

This server provides comprehensive MCP Resources support, enabling dynamic feed discovery, real-time subscriptions, and advanced filtering capabilities.

Resource Types

The server exposes feed data through structured resource URIs:

1. Feed List Resource

URI: feeds://all
Description: Lists all configured feeds with metadata
Content: JSON array of feed objects with titles, descriptions, and URLs
Use Case: Discover available feeds dynamically

2. Individual Feed Resources

URI: feeds://feed/{feedId}
Description: Complete feed data including metadata and all items
Content: JSON object with feed metadata and items array
Use Case: Get full feed content in a single request

3. Feed Items Resources

URI: feeds://feed/{feedId}/items
Description: Feed items only (no metadata)
Content: JSON array of feed items
Use Case: Focus on content without feed metadata overhead
Supports: Advanced filtering via URI parameters (see below)

4. Feed Metadata Resources

URI: feeds://feed/{feedId}/meta
Description: Feed metadata only (no items)
Content: JSON object with feed title, description, author, etc.
Use Case: Quick feed information lookup

Advanced URI Parameter Filtering

Feed items resources support comprehensive filtering via URI parameters:

feeds://feed/{feedId}/items?limit=10&since=2024-01-01&category=tech&search=AI

Supported Parameters:

since - Items published after date (ISO 8601: 2024-01-01T00:00:00Z)
until - Items published before date (ISO 8601: 2024-12-31T23:59:59Z)
limit - Maximum number of items (1-1000, default: all)
offset - Skip first N items (for pagination)
category - Filter by category/tag (case-insensitive)
author - Filter by author name (case-insensitive)
search - Full-text search in title, description, and content (case-insensitive)

Filter Examples:

# Recent items only
feeds://feed/abc123/items?since=2024-01-01T00:00:00Z

# Paginated results
feeds://feed/abc123/items?limit=20&offset=40

# Category and search combined
feeds://feed/abc123/items?category=technology&search=artificial+intelligence

# Date range with limit
feeds://feed/abc123/items?since=2024-01-01&until=2024-01-31&limit=10

Resource Subscriptions

The server supports MCP resource subscriptions for real-time feed updates:

Automatic notifications when feed content changes
Session-based subscription management with cleanup
Thread-safe operations for concurrent subscribers
Cache integration with invalidation triggering notifications
Efficient change detection using content hashing and timestamps

Performance Characteristics

MCP Resources are optimized for high performance:

Resource listing: ~0.17ms for 100 feeds (588x faster than requirements)
Resource reading: ~0.008ms for cache hits (6,250x faster than requirements)
Memory efficient: ~25KB per feed with linear scaling
Concurrent access: Excellent scaling with minimal contention
Cache integration: Sub-microsecond cache hits with 95%+ hit ratio

Usage Examples

List all available feeds:

{
  "method": "resources/read",
  "params": {
    "uri": "feeds://all"
  }
}

Get specific feed with recent items:

{
  "method": "resources/read", 
  "params": {
    "uri": "feeds://feed/abc123/items?since=2024-01-01&limit=10"
  }
}

Subscribe to feed updates:

{
  "method": "resources/subscribe",
  "params": {
    "uri": "feeds://feed/abc123/items"
  }
}

Migration from Tools to Resources

For existing integrations using MCP Tools:

all_syndication_feeds tool → feeds://all resource
get_syndication_feed_items tool → feeds://feed/{feedId}/items resource
Tools remain supported for backward compatibility
Resources provide richer metadata and filtering capabilities
Subscriptions enable real-time updates not available with tools

Running via docker

docker run -i --rm ghcr.io/richardwooding/feed-mcp:latest run \
  https://www.reddit.com/r/golang/.rss \
  https://www.reddit.com/r/mcp/.rss

Running via podman

podman run -i --rm ghcr.io/richardwooding/feed-mcp:latest run \
  https://www.reddit.com/r/golang/.rss \
  https://www.reddit.com/r/mcp/.rss

Installing using Go install

You can install the CLI using:

go install github.com/richardwooding/feed-mcp@latest

Add to Claude Desktop

In your Claude Desktop configuration file, add the following configuration to the mcpServers section:

Docker

{
  "mcpServers": {
    "feed": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://www.reddit.com/r/golang/.rss",
        "https://www.reddit.com/r/mcp/.rss"
      ]
    }
  }
}

Podman

{
  "mcpServers": {
    "feed": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/richardwooding/feed-mcp:latest",
        "run",
        "https://www.reddit.com/r/golang/.rss",
        "https://www.reddit.com/r/mcp/.rss"
      ]
    }
  }
}

Security

feed-mcp includes several security features to protect against common web vulnerabilities:

URL Validation

Scheme restriction: Only HTTP and HTTPS URLs are allowed
Private IP blocking: Prevents SSRF attacks by blocking access to private IP ranges by default
Localhost protection: Blocks localhost, 127.x.x.x, and IPv6 loopback addresses
Malformed URL detection: Rejects invalid or malicious URL formats

Private IP Ranges Blocked by Default

10.0.0.0/8 (10.x.x.x)
172.16.0.0/12 (172.16-31.x.x)
192.168.0.0/16 (192.168.x.x)
127.0.0.0/8 (localhost/loopback)
169.254.0.0/16 (link-local)
IPv6 loopback (::1) and link-local addresses

Configuration Options

# Allow private IPs and localhost (disabled by default for security)
go run main.go run --allow-private-ips https://localhost/feed

# Using Docker
docker run -i --rm ghcr.io/richardwooding/feed-mcp:latest run \
  --allow-private-ips \
  https://192.168.1.100/api/feed

Security Best Practices

Always validate feed URLs before deployment
Use HTTPS URLs when possible for encrypted transport
Regularly update to the latest version for security patches
Consider network-level restrictions for additional protection
Monitor logs for blocked URL attempts

Dependencies

This project makes use of the following open source libraries:

gofeed — RSS/Atom feed parser
kong — Command-line parser
gocache — Caching library
ristretto — High performance cache
golang.org/x/time/rate — Token bucket rate limiter
sony/gobreaker — Circuit breaker pattern implementation
MCP Go SDK — Official MCP protocol implementation

License

This project is licensed under the MIT License.

Feed

feed-mcp

Quick Start Examples

OPML Support

Using OPML Files

Docker with OPML

OPML Format Support

Key Features

Exporting from Popular Feed Readers

Dynamic Feed Management (Phase 1)

Enabling Dynamic Feed Management

Available Management Tools

add_feed - Add New Feeds at Runtime

remove_feed - Remove Feeds by ID or URL

list_managed_feeds - View All Feeds with Metadata

Feed Sources and Metadata

Feed Status Tracking

Integration Examples

Claude Desktop Configuration

Building a Feed Aggregator

Security and Validation

Performance Characteristics

Phase 2 Roadmap

Limitations (Phase 1)

MCP Prompts Support (Phase 2)

Available Intelligence Prompts

analyze_feed_trends - Content Trend Analysis

summarize_feeds - Comprehensive Feed Summaries

monitor_keywords - Intelligent Keyword Tracking

compare_sources - Multi-Source Analysis

generate_feed_report - Detailed Performance Reports

Technical Implementation

Integration with Claude Desktop

Advanced Use Cases

Content Strategy Planning

Competitive Intelligence

Editorial Analytics

Future Enhancements (Phase 3)

Features

Architecture

How it Works

MCP Resources Support

Resource Types

1. Feed List Resource

2. Individual Feed Resources

3. Feed Items Resources

4. Feed Metadata Resources

Advanced URI Parameter Filtering

Resource Subscriptions

Performance Characteristics

Usage Examples

Migration from Tools to Resources

Running via docker

Running via podman

Installing using Go install

Add to Claude Desktop

Docker

Podman

Security

URL Validation

Private IP Ranges Blocked by Default

Configuration Options

Security Best Practices

Dependencies

License

Related Servers

Browser Use

Firecrawl

MCP Orlen Wholesale Price

Playwright Server

XPath MCP Server

MCP Browser Console Capture Service

Wayback Machine

Bright Data

Playwright Server

LinkedIn Profile Scraper

`add_feed` - Add New Feeds at Runtime

`remove_feed` - Remove Feeds by ID or URL

`list_managed_feeds` - View All Feeds with Metadata

`analyze_feed_trends` - Content Trend Analysis

`summarize_feeds` - Comprehensive Feed Summaries

`monitor_keywords` - Intelligent Keyword Tracking

`compare_sources` - Multi-Source Analysis

`generate_feed_report` - Detailed Performance Reports